DEV Community: Bryan Clark

Two alert lanes: the siren shouldn't depend on an LLM

Bryan Clark — Fri, 21 Aug 2026 16:05:14 +0000

Don't put a model in the path of the alarm that matters most. Split the notification router in two: alarm/emergency go straight to the Telegram Bot API from the SignalK plugin — no gateway, no model, no billing relationship — while alert/warn wake an agent turn that reads the vessel and writes one considered message. The lane that matters most then depends on the fewest components. Jump to the fix.

In June I wrote up the first generation of this: a zero-dependency SignalK relay that turned a notification into a phone push in about a second. This is the second generation, and it exists because that relay came out of the stack and I briefly replaced a one-second push with a twelve-hour one.

Problem: the alarm path became a cron job

The relay's push service went away, and what filled the gap was an agent gateway running a scheduled boat check:

0 7,19 * * *    boat-watch    # wake the agent, ask it to look at the vessel

Twice a day. A condition arising at 02:00 waits until 07:00. Worst-case alarm latency went from about a second to about twelve hours. That is survivable only because my boat is ashore and the vessel data is mocked; it is not survivable with real sensors.

The naive fix is obvious and wrong:

* * * * *    boat-watch    # every minute — problem solved?

Latency fixed, shape still wrong. Every notification now goes through a model turn, so a dragging anchor waits on an LLM round trip — and inherits every way that round trip can fail. The alarm that matters most ends up gated behind the slowest, most expensive, least reliable component in the stack, and the failure is silent: an agent that never wakes looks exactly like a quiet boat.

Diagnosis: count the things that have to work

My first instinct was "fine, send hard alarms through the gateway, just faster." That turns out not to be possible, and the reason it isn't is what produced the design.

The gateway's inbound hook surface exposes exactly two actions — wake and agent — and both of them run a model turn. There is no no-model message-send endpoint over HTTP. There is a CLI that can send a plain message, but it's a client over the gateway's WebSocket RPC, not something a plugin can call.

So "route the siren through the gateway for tidiness" means the siren depends on:

SignalK  →  router  →  internet  →  gateway process  →  hook token
                                 →  model API  →  provider account in good standing

Six things, two of which are somebody else's business relationship with me. Whereas going straight to the messaging platform's Bot API depends on:

SignalK  →  router  →  internet

Three things, all of which have to be up anyway for a notification to exist and leave the boat. Once you write both chains down, the split writes itself.

A hard alarm takes both lanes: the siren immediately, and a follow-up agent turn that adds context when — if — it's ready. The siren has to stand alone, because on a bad day it's the only message that arrives.

What I tried, and why each one failed

1. A path allowlist to decide what pages

The first routing rule I wrote was a list of paths worth waking someone for:

// don't do this
const PUSH_PATHS = [
  /^navigation\.anchor$/,
  /^electrical\.batteries\..*\.voltage$/,
  /^mob$/,
];
const shouldPush = (path, state) =>
  rank(state) >= rank('warn') && PUSH_PATHS.some((re) => re.test(path));

It fails on contact with real data. The whale-protection zone plugin I run raises zone presence as a warn, and those zones blanket most of the waterways here — so "inside a restricted area" is the normal condition, not an exception. Every SignalK restart re-fires them. Under a severity-only rule that's a page on every restart; under an allowlist it's fine right up until a new plugin ships an alarm you forgot to add, and then it's silent. An allowlist for alarms is a denylist you maintain by getting paged.

The data already had the answer in it:

{
  "path": "notifications.navigation.restrictedArea.<zone-id>",
  "value": {
    "state": "warn",
    "method": ["visual"],
    "message": "Inside 400m Approach Distance Prohibition"
  }
}

method: ["visual"] is the publisher saying display this, do not sound it. Meanwhile every distress plugin I run sets method: ["visual", "sound"]. The publishers had been declaring their intent the whole time and my router was ignoring it in favour of a regex list I'd have to keep current forever.

So: method decides whether a notification pushes at all; state only picks the lane. No allowlist anywhere. If something routes wrong, it gets fixed at the publisher, which is where the knowledge actually lives.

2. A coalesce window re-armed on every arriving row

The soft lane batches — one SignalK restart can transition six paths at once, and six concurrent agent turns is both a spam burst and a bill. My first window was the obvious one:

// don't do this either
function onSoftRow(row) {
  pending.push(row);
  clearTimeout(flushTimer);              // "reset the window"
  flushTimer = setTimeout(flush, 10_000);
}

That's a sliding window, and a sliding window is a promise that a steady trickle never gets delivered. Rows arriving every 4 seconds reset a 10-second timer forever; the batch grows and never flushes. Which is a strange thing to build into the path of "something is wrong on the boat."

The predecessor to this plugin had a coalesce(transitions, window_s) function with five tests asserting that the window runs from the oldest pending row. None of them got ported, because the timer is the rule once you arm it in the right place:

// The window runs from the OLDEST pending row: arm once when the buffer goes
// non-empty, never re-arm while one is in flight.
function armFlush() {
  if (flushTimer) return;
  const ms = (currentOptions.coalesceSeconds ?? 10) * 1000;
  flushTimer = setTimeout(flushSoft, ms);
  if (flushTimer.unref) flushTimer.unref();
}

if (flushTimer) return; is the entire fix, and it makes the property structural rather than asserted.

3. Posting `{"message": "..."}` to the agent hook

The soft lane looked healthy for weeks. The hook returned 200, the gateway logged an agent turn, the turn ran and read the vessel. Nobody ever got a message.

$ curl -sS -X POST "$HOOK_URL" -H "Authorization: Bearer $HOOK_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"message":"tank level rising"}'
{"ok":true,"runId":"..."}

# ...and in the gateway's run log:
Delivering to Telegram requires target <chatId>

The gateway takes the delivery target as a body field, not something implied by the hook URL. Both the old Python sidecar and the plugin's first cut posted only message, so every soft alarm since the sidecar era had completed an agent turn and then dropped the answer on the floor. A 200 from a hook endpoint means admitted, not delivered, and I had been reading it as the latter.

The fix stays gateway-agnostic — the plugin merges an opaque JSON blob the operator supplies, and never learns anyone's field names:

{
  "hookBodyExtra": "{\"deliver\":true,\"channel\":\"telegram\",\"to\":\"123456789\"}"
}

body: JSON.stringify({ ...parseHookExtra(opts.hookBodyExtra), message }),

message is spread last, so operator JSON can never clobber it.

The fix

Two lanes, one classifier, and the classifier is nine lines:

const HARD = new Set(['alarm', 'emergency']);   // siren + agent follow-up
const SOFT = new Set(['alert', 'warn']);        // agent turn only

// Which push lane this notification takes, or null for no push.
function classify(state, method) {
  if (state == null || INACTIVE.has(state) || !(state in SEVERITY)) return null;
  if (!Array.isArray(method) || !method.includes('sound')) return null;
  if (HARD.has(state)) return 'hard';
  if (SOFT.has(state)) return 'soft';
  return null;
}

Routing is then a shape, not a policy engine:

function route(rows) {
  const hardEnvs = [];
  for (const row of rows) {
    const lane = classify(row.state, row.method);
    if (lane === 'hard') hardEnvs.push(buildEnvelope(row, position()));
    else if (lane === 'soft') pendingSoft.push(row);
  }

  // Hard lane fires per-row immediately and never coalesces — deduplication is
  // a comfort feature, a missed alarm is not.
  for (const env of hardEnvs) deliver('telegram', () => sendTelegram(renderSiren(env), opts));
  for (const env of hardEnvs) deliver('hook', () => postHook(renderFollowupPrompt(env), opts));

  if (pendingSoft.length) armFlush();
}

The hard sender is a bare fetch to the platform's Bot API. No SDK, no gateway, nothing between the plugin and the internet:

async function sendTelegram(text, opts) {
  const res = await fetch(
    `https://api.telegram.org/bot${opts.telegramBotToken}/sendMessage`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ chat_id: opts.telegramChatId, text }),
      signal: AbortSignal.timeout(10000),
    }
  );
  if (!res.ok) throw new Error(`telegram sendMessage failed: HTTP ${res.status}`);
}

Two details in that function are load-bearing. The bot token is in the request URL, so the error path checks res.status by hand and never surfaces res.url or a raw transport error — a rejected fetch whose message carried the URL would write the token verbatim into the server log. And deliver() is fire-and-forget rather than awaited, so a wedged gateway can't serialize a later row's siren behind an earlier row's hook timeout.

Verified the way you'd want it verified — stop the gateway, inject a real distress notification, watch what happens:

$ systemctl --user stop <agent-gateway>
$ node scripts/inject-test-notification.js --path test.hardLane \
    --state alarm --method visual,sound --message "TEST - ignore"

# SignalK log:
delivery error on the hook lane: fetch failed
# Telegram: the siren arrived anyway.

Why it matters, and the gotchas nearby

The routing rule binds every path that can reach a human, not just the router. The plugin is not the only thing that reads the notifications tree — there's also a once-daily dead man's switch, an independent agent run whose whole job is to notice that an event-driven router has gone quiet (a router that has stopped emitting is indistinguishable from a calm boat). It reads SignalK on its own, so it needed its own copy of the method rule. It didn't have one, and on its first real scheduled fire it happily paged me about the standing zone warn that the router had been correctly ignoring. The rule now lives in three implementations that must stay in step, and "anything new that reads the notifications tree and can reach a human gets the rule before it ships" is a written policy rather than a thing I remember.

A correct config file is not evidence a lane is live. I spent an evening debugging a soft lane whose on-disk config was perfect — URL, token, body extras all set — and which routed nothing and logged nothing. The plugin instance was still holding pre-save config; the last relevant line in the server log was from before the edit. The only positive evidence a lane will deliver is the startup line:

if (!currentOptions.telegramBotToken || !currentOptions.telegramChatId) {
  app.error('no Telegram bot token/chat id — the hard lane (siren) will NOT deliver');
}
if (!currentOptions.hookUrl || !currentOptions.hookToken) {
  app.error('no agent hook URL/token — the soft lane will NOT deliver');
}

$ docker logs signalk | grep notification-router
signalk-notification-router: no agent hook URL/token — the soft lane will NOT deliver

That line, after the restart that followed the config save, is the check. Nothing else is.

method gates before severity, and it gates silently. A test notification at alert with method: ["visual"] is dropped by classify on purpose, with no log line at all — correct behaviour that is completely indistinguishable from a broken lane while you're testing one. Test with an injector that sets method explicitly:

SIGNALK_TOKEN=... node scripts/inject-test-notification.js \
  --path test.softLane --state warn --method visual,sound --message "TEST - ignore"

(A PUT to the notifications REST path returns 404 — no handler is registered. The delta WebSocket is the only way in.)

The lane split survived the rewrite, which is the real test of it. All of the above started life as a Python sidecar polling SignalK's REST API every 5 seconds, walking the notification tree, and hand-rolling edge detection. Moving it into an in-process SignalK plugin deleted the poll timer, the tree walk, the edge-trigger bookkeeping, a container, and a network_mode: host workaround — the delta subscription gives you all of it. The one property I refused to let dissolve in the port was the hard lane's short dependency chain. In-process is fine (if SignalK is down there are no notifications to route), but the siren still goes straight out to the Bot API rather than being routed through the agent for tidiness.

Close

This is the notification plumbing for an all-electric charter catamaran, where "the anchor is dragging" has to reach a phone whether or not a language model is having a good night. The plugin is MIT and on npm as @sailingnaturali/signalk-notification-router — source on GitHub, including the classify and armFlush code above and the tests around them.

SignalK's two token classes: why plugin routes 401 your device token

Bryan Clark — Sun, 16 Aug 2026 16:05:06 +0000

TL;DR — SignalK server has two token classes with different powers. A device token (Security → Access Requests) can write data — deltas, PUTs — but gets 401 Permission Denied on every /plugins/<id>/* and /skServer/* route, because those are admin-gated and a device token is readwrite, not admin. Plugin REST APIs need a user JWT from POST /signalk/v1/auth/login — and that JWT silently expires per the expiration field in security.json (the field the admin UI calls "Remember Me timeout"; the code falls back to 1h). Jump to the fix.

Our agent writes log entries through the signalk-logbook plugin's REST API. One day we went looking for a specific entry and found the log had a week-long hole in it. No crash, no alert, nothing in the dashboards — every read of the system looked perfectly healthy. The writes had been dying with a 401 the entire time, and the client's fire-and-forget POST swallowed every one.

The 401 turned out to be two different auth problems stacked on top of each other, and both come from the same under-documented fact: a SignalK server's auth surface differs per route class, and the two kinds of token it mints are not interchangeable.

Problem

The setup is ordinary: a SignalK server in Docker with security enabled and allow_readonly on, and an automation client that reads vessel data anonymously and writes log entries with a bearer token.

Reads: fine, no token needed —

$ curl -s http://localhost:3000/signalk/v1/api/vessels/self/navigation/position
{"meta":{...},"value":{"longitude":...,"latitude":...},...}

Writes to the plugin's REST API with the token we had: not fine —

$ curl -s -X POST -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"text":"Test entry"}' \
    http://localhost:3000/plugins/signalk-logbook/logs
You do not have permission to view this resource, <a href='/admin/#/login'>Please Login</a>

With an Accept: application/json header the same rejection comes back as:

{"error":"Permission Denied"}

And because the client treated the POST as fire-and-forget, that response went nowhere. The read path being anonymous is exactly what made this invisible: everything you'd casually check — positions, dashboards, the admin UI — kept working, because none of it exercises the write path or the token.

Diagnosis: two token classes

SignalK mints two different kinds of bearer token, and they pass different gates.

Device tokens come from the access-request flow (spec): the client POSTs to /signalk/v1/access/requests, the admin approves it under Security → Access Requests and picks a permission level. The JWT carries a device claim, and the principal it resolves to has the granted permission — typically readwrite.

User JWTs come from logging in as a user account:

$ curl -s -X POST -H 'Content-Type: application/json' \
    -d '{"username":"agent","password":"..."}' \
    http://localhost:3000/signalk/v1/auth/login
{"timeToLive":3600,"token":"eyJhbGciOiJIUzI1NiIs..."}

The JWT carries an id claim, and the principal resolves to the user's type — which can be admin.

Why it matters: in src/tokensecurity.ts, ordinary data writes only require readwrite:

// writeAuthenticationMiddleware — deltas, PUTs
if (
  skReq.skPrincipal?.permissions === 'admin' ||
  skReq.skPrincipal?.permissions === 'readwrite'
) {
  return next()
}

…but every plugin route and a list of server routes are mounted behind the admin middleware:

;[
  '/restart', '/runDiscovery', '/plugins', '/appstore', '/security',
  '/settings', '/backup', '/restore', '/providers', '/vessel', '/serialports'
].forEach((p) =>
  app.use(`${SERVERROUTESPREFIX}${p}`, adminAuthenticationMiddleware(false))
)

app.use('/plugins', adminAuthenticationMiddleware(false))

SERVERROUTESPREFIX is /skServer, and anything a plugin registers with registerWithRouter is mounted under /plugins/<plugin.id> — so the entire REST API of every plugin sits behind that last line. adminAuthenticationMiddleware accepts exactly one permission:

function hasAdminAccess(req: Request): boolean {
  return (
    skReq.skIsAuthenticated === true &&
    skReq.skPrincipal !== undefined &&
    skReq.skPrincipal.permissions === 'admin'
  )
}

So a readwrite device token is simultaneously good enough to write vessel data and permanently insufficient for any plugin's HTTP API. Same server, same Authorization header, different gate per route class. (You can approve a device as Admin in current server versions, but the UI defaults to Read Only and the natural choice for a data-writing device is Read/Write — which is how you end up here.)

What we tried (and why it failed)

Attempt 1 — re-mint the device token. First theory: the token expired. New access request, approved with permission Read/Write and Token Expiry NEVER. Data writes confirmed working — a course-API PUT (gated on readwrite, like deltas) goes through fine:

$ curl -s -X PUT -H "Authorization: Bearer $DEVICE_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"position": {"latitude": 48.86, "longitude": -123.35}}' \
    http://localhost:3000/signalk/v2/api/vessels/self/navigation/course/destination
{"state":"COMPLETED","statusCode":200,"message":"OK"}

…and the plugin route still 401s:

$ curl -s -o /dev/null -w '%{http_code}\n' -X POST \
    -H "Authorization: Bearer $DEVICE_TOKEN" \
    http://localhost:3000/plugins/signalk-logbook/logs
401

This is the maximally confusing state: the token demonstrably works — for writes, even — so it never occurs to you that the token is the wrong kind. It's not expired, not malformed, not missing a scope you can see anywhere. It just can't pass the admin gate, and nothing in the 401 body says so.

Attempt 2 — user JWT. Worked… for a while. Once we read the routing code above, the fix seemed obvious: create a user account, log in, use that JWT:

$ curl -s -X POST -H 'Content-Type: application/json' \
    -d '{"username":"agent","password":"..."}' \
    http://localhost:3000/signalk/v1/auth/login | jq -r .token
eyJhbGciOiJIUzI1NiIs...

$ curl -s -o /dev/null -w '%{http_code}\n' -X POST \
    -H "Authorization: Bearer $USER_JWT" ... \
    http://localhost:3000/plugins/signalk-logbook/logs
200

Victory. Then, days later, the writes went dark again — this time with a different string in the log:

$ curl -s -H "Authorization: Bearer $USER_JWT" \
    http://localhost:3000/plugins/signalk-logbook/logs
bad auth token

The clue was in the login response the whole time: "timeToLive": 3600. User JWTs expire according to the server-side expiration field in security.json; the code falls back to 1h when it's unset, and whatever short value your install carries, your freshly minted "fix" dies with it:

// login() — src/tokensecurity.ts
const theExpiration = configuration.expiration || '1h'
if (!isNever(theExpiration)) {
  jwtOptions.expiresIn = theExpiration as StringValue
}

Device tokens let you pick "NEVER" at approval time, right in the UI. User JWTs give you no such prompt — the TTL is a server-wide setting, and in the admin UI it hides under Security → Settings → "Remember Me timeout" ("How long server keeps you logged when Remember Me is checked in login"). Nothing tells you that same field is the lifespan of every token POST /signalk/v1/auth/login mints for your headless clients.

And note it's now worse than having no token: allow_readonly only applies when no token is sent. An expired token on the request 401s even plain reads:

// Token was provided but is invalid/revoked — always reject.
// allow_readonly only applies when no token is provided at all.
res.status(401).send('bad auth token')

The fix

Two parts: a long-lived user JWT, and a re-mint procedure for when it eventually dies anyway.

1. Set the server-side expiration, then mint. Either edit expiration in security.json and restart the server (~/.signalk/security.json; in Docker that's inside the container's home volume) —

{
  "expiration": "365d",
  ...
}

$ docker restart signalk
$ curl -s -X POST -H 'Content-Type: application/json' \
    -d '{"username":"agent","password":"..."}' \
    http://localhost:3000/signalk/v1/auth/login
{"timeToLive":31536000,"token":"eyJ..."}

— or skip the login endpoint entirely and mint a token offline with the bundled utility, which signs against security.json's secretKey with whatever TTL you ask for:

$ signalk-generate-token -u agent -e 1y -s ~/.signalk/security.json
eyJhbGciOiJIUzI1NiIs...

The same "Remember Me timeout" field in Security → Settings edits the value from the UI if you'd rather not touch the file — just know that's the knob you're turning.

2. Store the login creds next to the token, not just the token. The token will expire — a year out, or the day someone rotates secretKey. Keep SIGNALK_USER / SIGNALK_PASSWORD in the client's env alongside the JWT, so re-minting is one curl and not an archaeology dig. Better: have the client check timeToLive at mint time and log the expiry date somewhere a human will see it.

3. Make the write path prove itself. The actual root cause was never the token — it was a write path that could fail forever without anyone noticing, twice. Fire-and-forget writes to an authed endpoint need, at minimum, surfacing of non-2xx responses; ideally an end-to-end check that reads back something it recently wrote. A healthy-looking read path tells you nothing about the write path when reads are anonymous and writes are authenticated — they don't even share an auth gate to fail together.

Why it matters / gotchas

"The token works" is not "the token works here." One server, two token classes, three permission levels, and per-route-class gates. Data writes check readwrite; /plugins/* and /skServer/* check admin. When you hit a 401 with a token that provably works elsewhere, ask which middleware is in front of this route class before re-minting anything.
The expiration knob is disguised. security.json's expiration governs every user JWT the login endpoint mints, but the admin UI labels it "Remember Me timeout" and describes it purely in browser-login terms. If your headless client's JWT keeps dying, this is the field.
An expired token is worse than none. allow_readonly grants anonymous tokenless requests a readonly principal — but a request carrying an expired or bad token is always rejected, reads included (bad auth token). A client that "falls back to readonly" by keeping its stale header set doesn't fall back at all.
Pending access requests don't survive a restart. They're held in an in-memory map on the server (requestResponse.ts), so if you restart between a device requesting access and the admin approving it, the request is simply gone — the device has to ask again. Approved devices are persisted to security.json.
The browser gets token refresh; your client doesn't. Past a JWT's half-life the server issues a refreshed token — as a session cookie. A headless client holding the raw bearer token from the login response never sees it, so browsers stay logged in indefinitely while your agent's identical token quietly ages out.

If you're the one writing the plugin

The same admin gate bites from the other side. A plugin that serves its data with registerWithRouter puts that data behind /plugins/<id>/* — admin-only, invisible to every anonymous or readwrite consumer, even with allow_readonly on. If what you're serving is data rather than admin actions, register a resource provider instead:

app.registerResourceProvider({
  type: 'myThings',
  methods: {
    listResources: (query) => { ... },
    getResource: (id) => { ... },
    setResource: (id, value) => { ... },
    deleteResource: (id) => { ... },
  },
})

That serves under /signalk/v2/api/resources/myThings — reads are open under allow_readonly, writes go through the normal readwrite check, and no consumer ever needs an admin credential to look at your data. Save registerWithRouter for genuinely admin-ish endpoints, or for plugins (like a logbook) whose API is deliberately write-capable and authed — and document which token class callers need, because the server's 401 won't.

Close

This all fell out of running an AI crew-agent that keeps the ship's log on an all-electric charter catamaran — the agent read the vessel state fine for a week while its log entries bounced off a gate nobody knew existed. The MCP server that now holds the long-lived JWT (and the re-mint procedure) is open source: github.com/sailingnaturali/logbook-mcp.

Related: Monitor the delivery path, not just the alarm — the same silent-401 failure shape, on the outbound notification leg · Adopt vs build: the ship's log — how the logbook stack this bit is put together.

How I proved a from-scratch harmonic tide engine is accurate

Bryan Clark — Sat, 15 Aug 2026 16:39:18 +0000

You wrote a tide engine. It computes a number: 1.42 m at 3:10 PM. How do you know
that number is right? You can't measure the future ocean. You can't diff against
"the truth" because the truth is a prediction too. This is the whole problem with a
from-scratch harmonic tide predictor — the output looks authoritative the day you
first run it, and authoritative-looking is not the same as correct.

TL;DR — Validate a harmonic tide engine on two axes. Algorithm: golden
vectors against a trusted oracle (@neaps/tide-predictor) — every layer to
floating-point agreement. Reality: head-to-head against the tide authority's
own published predictions — NOAA CO-OPS at Friday Harbor, max 7.9 min / 3.5 cm
across 12 highs and lows, inside the ±15 min / ±0.15 m you'd accept from a printed
table. And before you trust any of it: if your predictions read higher than the
printed tide tables, that's usually not a bug — it's the chart-datum offset.
Jump to the numbers.

The trap that makes a correct engine look wrong

Here's the first thing that will convince you your engine is broken when it isn't.

Compute the harmonic tide height for a station, line it up against the printed tide
tables for the same minute, and your number comes out higher — consistently,
by a fixed amount. The instinct is to hunt for the bug. There isn't one.

A harmonic sum is referenced to the datum its constituents were derived against —
typically mean sea level (MSL), the average of all water levels. Printed tide
tables and nautical charts are referenced to chart datum: MLLW (mean lower
low water) in the US, LAT (lowest astronomical tide) in Canada. Chart datum sits
below MSL by design — it's a low-water reference so that charted depths are
conservative. So a raw harmonic prediction reads higher than the table by exactly the
distance between the two datums.

The fix is a single per-station offset. In this engine it's one optional field on the
station:

let station = Station(
    constituents: [HarmonicConstituent(name: "M2", amplitude: 0.96, phase: 128) /* … */],
    offset: 1.387  // datum offset (e.g. MSL → MLLW), optional
)

And that offset isn't a fudge factor — it's published metadata. NOAA ships the datum
values per station; the offset is just their difference:

const fh = stations.find((s) => s.id === 'noaa/9449880');
const offset = fh.datums.MSL - fh.datums.MLLW; // shift MSL-relative harmonics to chart datum MLLW

The apps that "match the printed number" without applying this are the ones actually
carrying an error — they've hidden a datum mismatch by accident, or they never summed
the harmonics in the first place. Once you know the offset exists, it's a knob, not a
mystery. (This is a subtlety of the harmonic-prediction path — computing heights
from constituents versus reading a printed table. Hydrographic services like NOAA and
CHS serve their own predictions at their own stated datum; they're not wrong, they're
just answering a different question than a from-scratch sum does.)

That's the trap. Now the actual validation.

Method: golden vectors against an oracle

You can't test a predictor against the ocean. You can test it against another
predictor that's already trusted — and if the two agree to floating-point precision,
your port of the algorithm is faithful by construction.

The oracle here is @neaps/tide-predictor
@0.10.0, a well-exercised JavaScript harmonic engine. The Swift engine is a port of
its algorithm, so the bar isn't "close" — it's the same number. A Node tool
generates golden fixtures from Neaps; swift test replays them and asserts agreement
layer by layer:

swift test                    # golden validation against the Neaps reference
node tools/gen-golden.mjs     # regenerate golden fixtures from @neaps/tide-predictor
node tools/gen-realworld.mjs  # refresh the NOAA real-world fixture

The point of going layer by layer is that a tide prediction is a stack of
computations, and an error in any one of them hides inside a plausible-looking final
curve. Test the whole pipeline only end-to-end and a sign error in the node
corrections can cancel against a phase error somewhere else for the 48 hours you
happened to check. So each layer gets pinned independently:

Layer	Check	Tolerance	Result
Astronomy	mean longitudes + node angles, 8 times across the 18.6-yr nodal cycle	1e-6°	pass
Node corrections	IHO f/u, 17 base constituents × 3 times	1e-6	pass
Constituents	V₀ + compound f/u, ~39 constituents × 2 times	1e-6	pass
Prediction	48 h height series, mixed-tide set	< 1e-6 m	pass
Extremes	hi/lo count, kind, time, height	60 s / 0.02 m	pass

A few of these deserve a note on why they're the layers that break:

Astronomy across the 18.6-year nodal cycle. The moon's orbital plane precesses over 18.6 years, and the mean longitudes and node angle are sampled across that full cycle — not just at one date — because a bug in the node angle is invisible near one epoch and large near another.
Node corrections (the f/u factors). These are the per-constituent amplitude (f) and phase (u) adjustments that account for that same nodal modulation. They're the most common place a harmonic engine quietly drifts, which is why they get their own fixture instead of only being checked through the final height.
Extremes, not just the height curve. Sampling heights on a grid and calling the peaks "high tide" gives you the wrong minute. The extremes layer solves for the actual turning points and is checked on count, kind (high vs low), time, and height separately — the tolerances there (60 s, 0.02 m) are the tight ones.

Every layer lands at floating-point agreement (1e-6). The algorithm is faithful to
the reference. But "faithful to the reference" only proves the port is correct — it
says nothing about whether the reference matches the real world. That's the second
axis.

The datum offset is a step in the harness, not a footnote — it's the only thing standing between "agrees to a few centimetres" and "off by the whole MSL-to-MLLW gap."

The receipt: vs NOAA's own predictions

The stronger test is against a completely independent authority: NOAA's own published
predictions, straight from the CO-OPS Data Retrieval
API. This is a real head-to-head —
feed the engine the published harmonic constituents for a station, then compare its
highs and lows to what NOAA's own internal engine says for the same station and days.

Station: Friday Harbor, WA (NOAA 9449880). Constituents come from
@neaps/tide-database (sourced from
NOAA, public domain, bundled offline). The comparison target is fetched live from
CO-OPS at MLLW, GMT:

const url = `https://api.tidesandcurrents.noaa.gov/api/prod/datagetter`
  + `?begin_date=20260715&end_date=20260717`
  + `&station=9449880&product=predictions&datum=MLLW&interval=hilo`
  + `&units=metric&time_zone=gmt&format=json`;

Twelve highs and lows over 2026-07-15…17:

Metric	Engine vs NOAA	Navigational tolerance
Max time error	7.9 min	±15 min
Max height error	3.5 cm	±0.15 m

The engine reproduces NOAA's published tide tables to a few minutes and a few
centimetres — inside half the tolerance you'd accept from a paper table, on both axes,
computed entirely offline from the bundled constants. That's the claim that matters:
not "agrees with the code I ported from," but "agrees with the tide authority."

The honest residual — why ~8 minutes

I'm not going to tell you the error is zero, because it isn't, and the residual is
worth understanding rather than papering over.

The ~8 min / 3.5 cm gap against CO-OPS is expected. NOAA's operational engine
isn't the same engine — it uses a different node-correction epoch and a somewhat
different constituent set than the Neaps algorithm this port follows. Two correct
harmonic engines, fed the same station's constants but differing in those internals,
will land a few minutes apart. That's not error accumulating toward a wrong answer;
it's the known spread between two legitimate methods, and it sits an order of magnitude
inside navigational tolerance.

The tell that it's method-spread and not a bug: against the Neaps oracle — same
algorithm — the agreement is 1e-6, essentially exact. Against NOAA — different
algorithm — it's minutes. If the port were broken, the first number wouldn't be
floating-point tight. The two results are consistent with exactly one story: a faithful
port of one correct method, differing from another correct method by the amount two
correct methods differ.

A note on data sourcing

The constituents themselves are public. NOAA harmonic constants are public domain and
bundled with the engine (~3400 stations via @neaps/tide-database), which is what makes
offline prediction possible at all — no network, no key, no live dependency, predictions
years ahead from data that ships with the app. For Canadian waters, CHS publishes
predictions (not just constants) through its IWLS API, fetched and cached online.

One gotcha worth flagging for anyone bundling multi-source constants: constituent
naming isn't standardized. NOAA writes NU2, MM, RHO; CHS and other sources use
their own variants for the same physical constituents. Feed a station's published
constants straight in and the ones whose names don't match your catalog silently drop
out of the sum — a prediction that's subtly, plausibly wrong. The engine's catalog
resolves 83 aliases to canonical names so published constants from any source
predict correctly.

Close

A tide number you computed yourself is only worth anything if you can show your work.
Two axes do it: golden vectors prove the algorithm is a faithful port, and a
head-to-head against the authority's own predictions proves the port matches reality —
with the datum offset applied so you're comparing to the right zero. The engine is
MIT-licensed and the validation is reproducible from the fixtures:
slackwater-engine. If it's
off in your home waters, the fixtures are right there — check it and send a number back.

Not for navigation. Predictions are astronomical estimates and don't account for
weather, surge, or local effects. Carry official tables and charts.

Tide predictions read higher than the tables? Suspect the datum

Bryan Clark — Thu, 13 Aug 2026 20:11:11 +0000

TL;DR — If a harmonic tide prediction disagrees with the official tide
tables by a constant offset at a station, the algorithm is fine; the two
heights are measured from different zeros. Canadian chart datum is not
LAT — at CHS stations it sits up to ~0.43 m above it, and the per-station
offset is published in the CHS station /metadata API.
Jump to the fix.

Tide height numbers are meaningless without a stated vertical datum. Every
"3.2 m at 14:40" is really "3.2 m above some agreed zero", and there are
half a dozen zeros in circulation: mean sea level (MSL), mean lower low water
(MLLW), lowest astronomical tide (LAT), and each hydrographic office's own
chart datum. Compare two predictions that don't share a zero and you get a
bug report that looks exactly like broken code.

This is the story of one of those bug reports — against
signalk-tides, the SignalK
tide plugin — that turned out to be a datum mismatch, and of the
cross-checking that then turned up a genuinely broken station in the upstream
tide database.

Problem

signalk-tides v2 (2.0.0-beta.1,
after #78 went
Neaps-only) predicts tides offline from harmonic constituents — no NOAA,
no WorldTides, no API keys. It runs on our boat's SignalK server and answers
for any position:

curl "http://<signalk-host>:3000/signalk/v2/api/tides/extremes?latitude=48.649&longitude=-123.393"

Cross-checking it against the official CHS predictions for Sidney, BC
(station 07260) before trusting it for anchoring math:

validated against official CHS predictions, 2026-06-12

Sidney BC (07260):          every high and low +0.35 to +0.48 m HIGH
                            timing within ~16 min
Point Atkinson BC (07795):  heights within 0.03–0.13 m
                            timing within ~6 min

At Sidney, every single high and low read a consistent third-to-half metre
higher than the published tables — while Point Atkinson, checked the same
way on the same day, was nearly spot on. Timing was fine at both. The obvious
conclusion — the one any user would file
as an issue — is "the plugin over-reads by half a metre; the harmonic engine
is broken."

The same symptom was already sitting in the Neaps tracker as
openwatersio/neaps#223,
with a Halifax example:

// Neaps (TICON constituents), Halifax NS, 2026-02-20, datum: "MLLW"
{ t: 'Fri, 20 Feb 2026 01:38:10 GMT', level:  1.507 }
{ t: 'Fri, 20 Feb 2026 07:51:58 GMT', level: -0.068 }
{ t: 'Fri, 20 Feb 2026 13:51:17 GMT', level:  1.474 }
{ t: 'Fri, 20 Feb 2026 20:08:29 GMT', level: -0.136 }

// CHS official wlp-hilo predictions, same station, same day
{ "eventDate": "2026-02-20T01:36:00Z", "value": 1.817 }
{ "eventDate": "2026-02-20T07:57:00Z", "value": 0.310 }
{ "eventDate": "2026-02-20T13:46:00Z", "value": 1.774 }
{ "eventDate": "2026-02-20T20:09:00Z", "value": 0.181 }

Times agree to minutes. Levels are ~0.3 m apart — and uniformly apart.

Diagnosis

That uniformity is the whole diagnosis. Harmonic synthesis produces an
oscillation about the station's mean water level; getting from there to
"height above chart datum" is a per-station constant from a datum table, added
at the end. So:

A constituent error (bad amplitudes/phases) varies with the tide — big at springs, small at neaps, different at highs vs lows.
A datum error is DC — the same offset on every prediction, at every tide.

A constant offset means the sine waves are right and the zero is wrong.

Here the zeros genuinely differ. Neaps serves heights in the station's
chart_datum from the TICON-based tide database,
which labels Canadian stations "LAT" (lowest astronomical tide). CHS tide
tables are referenced to CHS chart datum. And the common assumption that
Canadian chart datum ≈ LAT turns out to be false at station level: CHS chart
datum sits above LAT by a per-station amount — 0.43 m at Sidney.

You don't have to take that on faith; CHS publishes every station's vertical
ladder in the IWLS /metadata endpoint:

# Sidney BC (station code 07260)
curl -s "https://api-iwls.dfo-mpo.gc.ca/api/v1/stations/5cebf1df3d0f4a073c4bbd26/metadata"
# resolve the heightTypeIds via:
curl -s "https://api-iwls.dfo-mpo.gc.ca/api/v1/height-types"

// metadata "heights", values in metres relative to CHS chart datum
{ "code": "MWL",   "value":  2.09 }   // mean water level
{ "code": "LLWLT", "value": -0.22 }   // lower low water, large tide
{ "code": "LAT",   "value": -0.43 }   // lowest astronomical tide
{ "code": "HAT",   "value":  3.53 }

LAT is 0.43 m below chart datum at Sidney — exactly the amount by which the
plugin's LAT-referenced predictions "over-read" against the chart-datum
tables. (Note LLWLT ≠ 0 either: even the textbook definition of Canadian
chart datum doesn't sit at the datum's actual zero here.)

What we tried (and why it failed)

Suspecting the constituents. The natural first read — offline harmonics
from a community database vs the hydrographic office, of course the
constituents are worse. But lining up TICON's own datum table against CHS's
published offsets shows the two agree almost exactly on where MSL sits above
LAT:

Station	TICON MSL→LAT	CHS metadata (MWL above CD + CD above LAT)	agreement
Sidney BC	2.522 m	2.09 + 0.43 = 2.52 m	~2 mm
Point Atkinson BC	3.144 m	3.09 + 0.08 = 3.17 m	~3 cm
Halifax NS	1.152 m	1.03 + 0.09 = 1.12 m	~3 cm

The physics agreed to centimetres. It was bookkeeping.

Comparing "MLLW to MLLW". The Halifax example above asked Neaps for
datum: "MLLW" and still missed by 0.3 m — because CHS wlp-hilo values
aren't MLLW-referenced (they're chart datum), and TICON's MLLW is its own
computed statistic. Two datums with the same name from two sources are not
the same zero.

Trusting the chart_datum: "LAT" label. The station records say chart
datum is LAT, so diffing against the tables should be safe… except CHS chart
datum isn't LAT (see above). A label is a claim, not a measurement.

The fix

Normalize both sides to one explicit datum before comparing — or before doing
any arithmetic at all with someone else's heights:

// CHS /metadata "heights": LAT is relative to chart datum (negative)
const lat = heights.find((h) => h.code === "LAT")!.value; // Sidney: -0.43

// shift CHS chart-datum predictions onto LAT…
const chsAboveLAT = chsPrediction.value - lat;

// …and ask the harmonic side for the same zero explicitly
const { extremes } = station.getExtremesPrediction({ start, end, datum: "LAT" });

Datum-aware, the "half a metre of error" collapses: Sidney residuals drop to
≤ ~8 cm, Point Atkinson ≤ ~5 cm, Halifax ~10–13 cm, timing within minutes
everywhere.

That normalization then became a standing benchmark, contributed upstream as
openwatersio/neaps#272: all
226 Canadian MEDS-sourced TICON stations diffed against live CHS predictions
(the TICON ids embed the CHS station code — sidney_bc-7260-can-meds —
so the join is free). Across the 180 stations that line up, full-year
height MAE is p50 7.3 cm / p90 16.4 cm / p95 25.7 cm, timing ~23 min
(p95 of median |Δt|), re-run monthly in CI against fresh CHS predictions.

The bonus find: a station no datum can explain

The benchmark's per-station CSV kicked out one outlier that is not a datum
problem: cape_dor-240-can-meds (Cape d'Or, Bay of Fundy) carries a +3.5 m
constant bias — and unlike the others, its harmonic record itself is
implausible. Filed upstream as
openwatersio/tide-database#93
(still open as of this writing):

TICON HAT−LAT:              18.58 m
CHS published HAT−LAT:      12.40 m   (same location)
one-year predicted range:   17.4 m    — would exceed the world-record
                                        range at Burntcoat Head
SA constituent:             2.08 m    — 4× the next-highest Canadian
                                        station; implausible for an
                                        open-marine site

Dropping the suspect SA term only brings the predicted range down to 16.0 m,
so the whole constituent set reads as over-amplified, not one bad row. The
point isn't this station — it's that benchmarking against published ground
truth catches upstream data errors, not just your own bugs. Nothing in the
code path was wrong; the input data was.

Why it matters / gotchas

Never trust a height without asking "above what?" Any pipeline that passes tide heights between systems should carry the datum with the number, and any comparison should normalize first.
The error signature tells you where to look. Constant offset across all tides → datum/bookkeeping. Error that scales with the tide → constituents. This one rule would have saved the original "water levels differ from the public tide predictors" investigation a lot of head-scratching.
The optimistic direction is the unsafe one. Charted depths are below chart datum. Add a LAT-referenced height to a charted depth where chart datum sits 0.4 m above LAT and you believe in 0.4 m of water that isn't there — exactly the wrong direction for under-keel clearance. Our agent tooling carries this as an explicit caveat and pads margins accordingly.
Per-station, not a constant. The CHS chart-datum-to-LAT offset is 0.43 m at Sidney, 0.08 m at Point Atkinson, 0.09 m at Halifax. There is no single fudge factor; the station /metadata is the source of truth.

Close

This came out of wiring signalk-tides v2 into the AI-ops stack we run on an
all-electric sailing catamaran — offline tide predictions the boat can answer
from with no internet, which is only useful if you've checked them against
the official tables first. The plugin, the
Neaps engine, and the
tide database are all open
source and better for the benchmarking.

Related: verifying forecasts against what a buoy is actually measuring is
the same habit applied to weather — see
why generic weather MCPs fail for marine navigation.

Shipping Canadian CHS station data without redistributing the licensed file

Bryan Clark — Wed, 12 Aug 2026 13:01:11 +0000

TL;DR — US tide/current station data (NOAA) is public domain and you can bundle it into anything. Canadian data (CHS) is not: the IWLS API licence forbids redistributing derivative products. The facts inside — names, positions — aren't copyrightable anywhere (Feist, CCH Canadian), and there's no EU-style database right in the US or Canada. So the constraint isn't copyright, it's the terms of use — a contract. The safe design ships your own independently-obtained registry that carries no provider-minted station id, and resolves CHS's opaque handle at runtime under your own API licence, joining by station name. Jump to the fix.

A quick disclaimer, said once: I'm an engineer reasoning about licences, not a lawyer, and none of this is legal advice. But the reasoning is the whole point of the post — if you're building a marine, mapping, or civic-data app on government open data and you hit "can I redistribute this?", the shape of the answer is worth having.

Problem

We predict tidal currents offline for a boat in the Salish Sea, which straddles the Canada/US border. Both national hydrographic offices publish the harmonic data that makes offline prediction possible. One of them lets you ship it. The other does not.

US — NOAA — public domain. NOAA publishes tidal-current harmonic constituents as public-domain data. Anyone can bundle them into anything, commercial or not, and offline prediction just works. There is no problem to solve here.

Canada — CHS — a bespoke Crown licence. The CHS licence agreement you accept by using the IWLS API is not the Open Government Licence. Three clauses bite:

Clause 3  — CHS copyrights "shall not be sold, licensed, leased, assigned
            or given to a third party."
Clause 4  — prohibits derivative products "for commercial purposes, for
            sale or profit under any form whatsoever."
Clause 10 — permits non-profit derivative products, provided you carry a
            prominent notice (your name, that it contains CHS IP, Crown
            copyright retained, not for navigation, CHS does not endorse it).

Clause 10 lets you derive data for your own non-commercial use. Clause 3 stops anyone from handing you — or you handing anyone — a finished bundle. So you cannot ship a Canadian tide/current dataset the way you ship a NOAA one.

That leaves a design question with a non-obvious answer: how do you ship a Canadian tide/current app — a station picker, a slack-window planner, a registry of gates — without redistributing CHS's file? The naive read is "you can't." The precise read is "you can ship everything except the one thing that is actually theirs."

Diagnosis: copyright vs. contract

The instinct is to reach for copyright — "are these facts protected?" — and that instinct sends you down the wrong road, because the answer is no, and it doesn't help.

Facts are not copyrightable. Two courts, two jurisdictions, say so directly.

US — Feist Publications v. Rural Telephone Service, 499 U.S. 340 (1991). A phone book's white pages got zero copyright protection. Compiling facts, however laborious, is not authorship; "sweat of the brow" was explicitly rejected. Only an original selection, coordination, or arrangement is thinly protected, and the underlying facts stay free for anyone to re-extract.
Canada — CCH Canadian v. Law Society of Upper Canada, 2004 SCC 13. Originality requires "skill and judgment," not mere labour. A factual list with an obvious arrangement is not protected.

And neither the US nor Canada has an EU-style sui generis database right, so the labour of assembling a station list creates no separate right, either. A station's name, latitude, and longitude are facts. You may re-state them from a chart, a gazetteer, or your own survey, and nobody owns your copy.

So copyright isn't the risk. The risk is contract. The IWLS licence is terms-of-use you agreed to in exchange for API access, and that agreement is separable from — and survives — the fact that the data inside is free. You can lawfully re-state every fact CHS knows; you cannot redistribute the file you pulled from them under their licence. The line isn't "which facts appear," it's "did you hand someone a copy of the provider's licensed product."

Which turns the whole problem into a question of method, and puts a spotlight on one specific field.

The tell: the opaque station id

Every CHS station has an internal handle — an opaque id like 63aef18… — that you fetch its data with. It looks like just another fact, and copyright-wise it is one. But it's a fact with a special property: it has no independent existence. You cannot derive a CHS station id from a chart or a gazetteer. The only place it comes from is CHS's licensed API. So a file that carries the id is, by construction, a slice of CHS's export — it is the one field that can only have been redistributed, and the one field that points straight back into their system.

That is the field to not ship.

What we tried (and why it crossed the line)

The honest version of this section is that our own earlier releases did the wrong thing, and we caught it.

Attempt 1 — ship the id as "just the join key." Version 1.5.0 of our station registry carried providerId on every record, treating it as harmless reference data — the handle a consumer needs to look up live current data:

# station-corrections registry.yaml — v1.5.0 (the version we walked back)
chs-dodd-narrows:
  name: Dodd Narrows
  context: Nanaimo
  position: [49.1344, -123.8171]
  provider: chs
  providerId: 63aef1866a2b9417c035030f   # ← CHS's opaque handle, redistributed

And the downstream fitting pipeline read exactly that field to fetch with:

// chs-constituents — the coupling we later removed
registry providerId -> StationRef.id    // what IwlsClient actually fetches

The problem: providerId is the one field on the record that isn't independently obtainable. name, context, and position we wrote ourselves from charts and our own fitting pipeline — those are our facts that happen to agree with CHS. But the id could only have come from CHS's API. Bundling it into a published npm package is handing a third party a piece of CHS's licensed export — precisely what clause 3 forbids ("given to a third party"). "It's just a reference" doesn't save it; the reference is the redistribution.

Attempt 2 — rationalize it as a bare fact. "But the id is a fact, and Feist says facts are free." True, and irrelevant: copyright was never the live risk. Terms-of-use is contract, and the contract restricts redistributing the file regardless of whether its contents are copyrightable. Winning the copyright argument doesn't win the licence argument. And there's a compilation-copyright trap hiding in the same instinct — see the gotchas.

Attempt 3 — the "just ship the whole CHS station table" temptation. Completeness feels safe ("it's a mirror of a public API"). It's the opposite: a complete list is the weakest possible compilation-copyright position (no original selection left to protect), and it maximizes the terms-of-use exposure by shipping the most of their file. Both readings point the same way — don't mirror their table.

The fix isn't to cite a case. It's to change the method so the provider's handle never enters the repository at all.

The fix: a pipeline, not a download

Here's the part worth internalizing before the code. On the US side, "add offline tide/current prediction" is essentially one API call against a public-domain endpoint — fetch, bundle, done. On the Canadian side the same feature takes a chain of pieces, each of which exists specifically to keep the licensed handle out of anything you publish:

The registry in the middle is the linchpin: it's the only stage that gets published, so it's the stage that must carry zero of CHS's file. The two ends touch CHS's licensed API — but only at runtime, on the operator's own machine, under the operator's own licence. A builder's real takeaway is that the Canadian version needs the whole chain; there's no single package that is both useful and shippable, because "useful" means resolving the licensed handle and "shippable" means not carrying it.

Two moves make each stage clean: remove the id from the published data, and resolve it at runtime under the operator's own licence.

1. The registry ships facts and zero provider ids

Version 2.0.0 dropped providerId (and a NOAA depth-cell providerBin) from the schema, the data, and the tests — a deliberate breaking change:

# station-corrections registry.yaml — v2.0.0
chs-dodd-narrows:
  name: Dodd Narrows
  context: Nanaimo
  position: [49.1344, -123.8171]
  provider: chs                 # the string "chs"/"noaa" — a fact, identifies the authority
  # no providerId. The stable key `chs-dodd-narrows` is the public id, safe in a URL.

$ git log --oneline
50c740a docs: registry ships no provider id; bump to 2.0.0
46410cf feat!: remove providerId/providerBin from registry data and fixtures
8dfea91 feat!: drop providerId/providerBin from the registry schema and validation

Everything left is a fact we obtained independently and reviewed by hand: the name (re-cased and cleaned from a shouting survey label), the position (from our own fitting pipeline and charts, audited against a coastline), the context. The provider string stays — "this is a CHS authority station" is itself a fact. The public join key is the station name (and its stable slug), which anyone is free to publish.

That "deliberately absent" id is the load-bearing move, so it's worth stating how the package itself frames it. Its PROVENANCE.md records provenance field by field — name is a hand-written label, context is written here, position is independently derived and human-verified — and then, for the provider id, one row that just reads:

provider id — Deliberately absent. The registry carries no provider-minted identifier at all — not even as a reference. A consumer joins a record here to a provider's live data by name; the provider's own opaque handle is resolved at runtime by whoever holds a licence to that provider's API, and it never enters this repository.

The registry isn't only used as an id-less lookup table, either — it's a four-tier resolver, so a consumer with any station reference lands on the same curated identity:

1. Registry        — stations this package owns outright (CHS gates with no
                     upstream record to correct). Resolves from a key alone.
2. Curated override — a hand-written correction wins over the provider's own name.
3. Derived fallback — nearest place from a bundled gazetteer, so context is never empty.
4. Source data      — the provider's own name, cleaned (upper-case → title-case).

None of the four tiers stores or emits a provider id. The dance is exactly this: tiers 1–4 traffic only in facts (names, positions, contexts) that agree with CHS because facts agree with facts — never because a byte was copied from CHS's file — and the one field that would point back into CHS's system is the one field the whole design refuses to hold.

2. Resolve the opaque handle at runtime, under your own licence

The id still has to exist somewhere — you need it to actually fetch current data. The move is to fetch it live, on the operator's machine, under the operator's own CHS API licence, and never write it to disk. The fitting pipeline lists CHS's stations live from the IWLS index and matches them to the registry by name:

// chs-constituents — the CHS id is fetched live and used only as a fetch handle
export function currentStations(raw: RawStation[]): IwlsStation[] {
  return raw
    .filter((s) => (s.timeSeries ?? []).some((t) => t.code === "wcsp1")) // current stations
    .map(({ id, officialName, latitude, longitude, operating }) => ({
      id, officialName, latitude, longitude, operating,
    }));
}

// The registry is a name overlay, NOT the id source. It reads no id at all:
export function stationsFromApi(stations: IwlsStation[], overlay: Map<string, OverlayEntry>) {
  return stations.map((s) => {
    const hit = overlay.get(normalizeName(s.officialName));
    // id: live from CHS, used only to fetch, never emitted.
    // key + curated label: from our registry, when the name matches.
    return hit ? { id: s.id, label: hit.label, key: hit.key } : { id: s.id, label: s.officialName };
  });
}

The join is a normalized-name match, applied symmetrically so a case/whitespace difference doesn't silently drop a station:

# currents-mcp — correlate a live plugin reading to a gate by name, not by id
def _norm(name: str) -> str:
    """Fold case and trim so a label/name differing only in casing still matches."""
    return name.strip().casefold()

# cache[_norm(station_label)] = events   ← keyed by name
# events_for_station(gate.name)          ← looked up by name

The CHS id lives for exactly as long as one fetch, on the operator's box, covered by the operator's own IWLS licence. It is never committed, never published, never handed to a third party. The registry, the vault, the npm package — none of them contain it.

That's the entire trick: the facts ship; the licensed handle resolves at runtime. Same functionality as the NOAA path — a consumer still gets a named station picker and offline predictions — reached by a more involved route because the licence demands it.

Why it matters / gotchas

Completeness is the weakest compilation-copyright position, not the strongest. Compilation copyright rewards original selection — deciding what to leave out. A complete list is unselective by definition, so there's no protectable selection left. If you're mirroring a whole provider table "to be safe," you're both maximizing the terms-of-use exposure and standing on the flimsiest copyright ground. Curate a bounded, rule-governed subset instead.
The rule is about method, not about which facts appear. A record that agrees with CHS on a coordinate is facts agreeing with facts. A byte-for-byte copy of CHS's export is redistributing their file. Same coordinate, different method, different answer. Write the facts yourself; don't paste their rows.
The identifier that can only come from the provider is the one to never ship. A name or a position you can re-derive from a chart. An opaque internal id you cannot — its only source is the licensed API, so shipping it is the redistribution. If a field has no independent origin, treat it as the provider's, and resolve it at runtime.
Contributor guidance falls straight out of the rule. For anyone adding a station: obtain the name, context, and position independently (chart, gazetteer, your own fitting pipeline, direct observation) and write them yourself; do not paste a row out of a provider's export, and do not add a provider-id field. If your workflow needs the provider's handle to join live data, resolve it there, under your own licence.
This isn't hypothetical — ask XTide. XTide once shipped Canadian harmonic constants with non-commercial notices attached; Debian packaged them separately as xtide-data-nonfree precisely because commercial distribution wasn't permitted. The author was then contacted by what he understood to be the Department of Justice Canada asking him to strengthen the warnings, stopped maintaining the non-US data in 2012, and XTide has shipped US-only ever since. A published notice is not a substitute for a licence you were never granted. That precedent is why we ship a pipeline and a factual registry, not a dataset.

Close

This came out of building offline current prediction for an all-electric charter catamaran working both sides of the Canada/US border, where "just bundle the tide data" is a one-liner on the US side and a licence analysis on the Canadian one. The whole pipeline is open source: the licence-clean identity layer in station-corrections (facts only, no provider ids, PROVENANCE.md documenting every field), the runtime-resolution end in chs-constituents (whose README walks the CHS licence clause by clause), and the by-name correlation in currents-mcp. Three stages, because the licence needs three; on the US side it would have been one.

Porting a tide engine to Swift with the original as the test oracle

Bryan Clark — Tue, 11 Aug 2026 16:07:47 +0000

TL;DR — Porting numeric code by hand and eyeballing the output is how you
ship plausible-looking wrong answers. Instead, treat the original
implementation as a test oracle: scripts that run the reference and dump
golden fixtures, one per algorithm layer, each ported layer gated on matching
the oracle to 1e-6 before the next begins. And when the port passes, you're
still not done — the last gate is matching reality, not the reference.
Repo: slackwater-engine.

We needed a pure-Swift harmonic tide/current prediction engine — tide math is
deterministic astronomy, so given a station's harmonic constituents you can
compute heights and high/low turns for any minute, years ahead, with zero
network. The best open reference implementation is
Neaps
(@neaps/tide-predictor, JavaScript, MIT). This post is about how we ported
it — the oracle-driven method — because the method transfers to any port of
numeric code between languages.

The problem: numeric ports fail silently

The Neaps algorithm is ~600 lines of real math: astronomical mean-longitude
polynomials, Doodson coefficients, Schureman/IHO node-correction formulas
full of terms like this one:

private func _nupp(_ N: Double, _ i: Double, _ omega: Double) -> Double {
    let I = d2r * _I(N, i, omega), nu = d2r * _nu(N, i, omega)
    let tan2 = pow(sin(I), 2) * sin(2 * nu) / (pow(sin(I), 2) * cos(2 * nu) + 0.0727)
    return r2d * 0.5 * atan(tan2)
}

Flip a sign in one of those, or mix degrees and radians once, and the engine
still produces beautiful sinusoidal tide curves — highs and lows in roughly
the right places, just quietly off by centimetres or minutes in ways that
drift with the 18.6-year lunar nodal cycle. Eyeballing plots against a tide
table catches none of it. A port validated by "looks right" is a liability
you discover at a shallow anchorage.

Wire the original up as an oracle

The fix is to make the reference implementation generate the tests. A small
Node script imports Neaps, evaluates each layer of the algorithm at fixed
instants, and writes the results as JSON fixtures the Swift tests load:

// tools/gen-golden.mjs — Neaps is the oracle. TideEngine (Swift) must match.
import { astro, constituents, createTidePredictor } from '@neaps/tide-predictor';

// Spread of UTC timestamps across the 18.6-year nodal cycle to exercise corrections.
const TIMES = [
  '2000-01-01T00:00:00Z', '2010-06-15T12:00:00Z', '2020-03-21T06:30:00Z',
  '2026-07-12T00:00:00Z', '2026-07-12T18:45:00Z', '2031-11-02T09:15:00Z',
  '2035-09-23T00:00:00Z', '2040-12-31T23:00:00Z',
];

write('astronomy.json', {
  note: 'Neaps astro(date) unwrapped to plain degrees; TideEngine must match within 1e-6.',
  times: TIMES,
  values: TIMES.map((t) => ({ time: iso(t), astro: unwrap(astro(new Date(t))) })),
});

Two properties make this an oracle rather than just "some tests":

Fixtures are generated, never hand-written. node tools/gen-golden.mjs regenerates every fixture from @neaps/tide-predictor@0.10.0. There is no opportunity to transcribe an expected value wrong, and bumping the oracle version re-derives the whole suite.
There's a fixture per layer, not just end-to-end. An end-to-end height comparison tells you that you diverged; a per-layer fixture tells you where. Every divergence is caught at the layer that caused it.

Port layer by layer, gate each layer

The algorithm decomposes into five layers, each consuming the one below.
Each got the same treatment: generate the fixture → write the failing Swift
test → port the math → gate on green before starting the next layer.

Layer	Golden check	Tolerance
Astronomy	15 quantities (mean longitudes + node angles) × 8 instants across the nodal cycle — 120 values	1e-6°
Node corrections	IHO f/u for 17 base constituents × 3 instants	1e-6
Constituents	V₀ + compound f/u for ~39 constituents (incl. M4, MS4, 2MK3)	1e-6
Timeline prediction	48 h height series, mixed-tide station, 10-min step	1e-6 m
Extremes	high/low count, kind, time, height	60 s / 0.02 m

Because both sides implement the same algorithm, the interesting tolerance is
floating-point agreement, not "close enough for tides." The prediction test
asserts both — the domain tolerance per point, and a divergence tripwire on
the max error:

var maxErr = 0.0
for (got, expected) in zip(points, fixture.points) {
    let err = abs(got.height - expected.height)
    maxErr = max(maxErr, err)
    #expect(err < 0.02, "height at \(expected.time): got \(got.height), want \(expected.height)")
}
// The engines share the algorithm, so agreement should be far tighter than 2cm.
#expect(maxErr < 1e-6, "max height error \(maxErr) exceeds 1e-6 — engines diverging")

If a future change drifts the port to, say, 5 mm of error — still a perfectly
plausible tide — the tripwire fires long before the domain tolerance would.

The per-layer gates earn their keep on the fiddly semantic mismatches between
the languages, because each one surfaces in the one layer it belongs to:

Timeline construction. Neaps floors the start and ceils the end to the step interval. Get that wrong and every sample is shifted — the astronomy and constituent layers stay green, and the prediction fixture pinpoints it.
Array identity vs value semantics. Neaps recomputes node corrections every 24 h and callers detect the refresh with a JS !== identity check. Swift arrays are value types — there is no identity. The port adds an explicit generation counter that callers compare instead. The extremes fixture is what proves the refresh logic actually matches.
What not to port. Neaps ships both Schureman and IHO node-correction schemes; the predictor only ever uses IHO. The oracle made that safe to verify — no fixture ever exercised Schureman, so it stayed unported.

Don't port the catalog — generate it

The single biggest porting risk wasn't the math — it was the data. Neaps
bundles ~5,000 lines of constituent definitions: 394 constituents with
speeds, Doodson coefficients, and compound-member decompositions, plus an
IHO Annex-B name parser that resolves compound names at runtime. Hand-porting
5,000 lines of numeric literals is transcription, and transcription is where
silent errors live.

So the catalog isn't code in the Swift port at all. A second codegen script
walks Neaps' constituent map and emits it as a bundled JSON resource — with
the name parsing already resolved:

// tools/gen-catalog.mjs — the IHO Annex-B name decomposition + sign resolution
// runs HERE, in Neaps, at build time; Swift consumes the resolved members
// and never needs the parser.
for (const key of Object.keys(constituents)) {
  const c = constituents[key];
  if (key !== c.name) aliases[key] = c.name;   // NOAA "NU2" → canonical "nu2"
  seen.set(c.name, {
    name: c.name,
    speed: c.speed,
    coefficients: c.coefficients ?? null,      // Doodson, when fundamental
    members: c.members?.map((x) => ({ name: x.constituent.name, factor: x.factor })),
  });
}

A compound constituent in the emitted catalog.json (52 KB, 394 constituents,
83 name aliases) looks like this:

{"name": "2MK3", "speed": 42.9271398,
 "coefficients": [3, -1, 0, 0, 0, 0, 1],
 "members": [{"name": "M2", "factor": 2}, {"name": "K1", "factor": -1}]}

And the entire Swift side of "compound constituent support" collapses to two
recursions over pre-resolved members:

/// Node correction (f, u°). IHO fundamental if the constituent has one, else
/// combined from members: f = Π f_memberᵃᵇˢ⁽ᶠᵃᶜᵗᵒʳ⁾, u = Σ factor·u_member.
func correction(_ name: String, _ a: Astro) -> (f: Double, u: Double) {
    let key = canonical(name)
    if let fundamental = ihoCorrection(key, a) { return fundamental }
    guard let e = byName[key] else { return (1, 0) }
    var f = 1.0, u = 0.0
    for m in e.members ?? [] {
        let c = correction(m.name, a)
        u += m.factor * c.u
        f *= pow(c.f, abs(m.factor))
    }
    return (f, u)
}

The aliases matter more than they look: real station data is inconsistent
about constituent names (NOAA publishes NU2, MM, RHO; the catalog's
canonical names are nu2, Mm, rho1), and the engine silently ignores
constituents it can't resolve. Without alias resolution, published harmonic
constants would predict — just with pieces of the tide missing.

Net result: the whole engine is 577 lines of Swift against Neaps'
~6,300-line bundle, because the 5,000 data lines crossed over as data.

Golden checks → `swift test` → CI

The first iterations ran as a throwaway command-line checker. Once the layers
were green, the checks converted to swift-testing
suites — fixtures under Tests/TideEngineTests/Fixtures/ — so the whole
oracle runs as plain swift test, and CI is 18 lines:

jobs:
  test:
    name: swift test
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: swift test

That conversion is worth calling out as its own step: an oracle that lives in
a side script rots; an oracle that is the test suite re-verifies the entire
port on every push, forever.

Matching the reference isn't the finish line

At this point the Swift engine reproduces Neaps to floating-point agreement.
That proves the port is faithful. It proves nothing about whether the
algorithm predicts actual water — if the reference had a bug, we ported the
bug at 1e-6 fidelity.

So the final gate compares against the tide authority itself. A third codegen
script takes published harmonic constants for Friday Harbor, WA
(NOAA 9449880, via @neaps/tide-database) and fetches NOAA's own official
high/low predictions from the CO-OPS API for the same window:

const fh = stations.find((s) => s.id === 'noaa/9449880');
const offset = fh.datums.MSL - fh.datums.MLLW; // shift MSL-relative harmonics to chart datum

const url = `https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?...`
  + `&station=9449880&product=predictions&datum=MLLW&interval=hilo&units=metric&time_zone=gmt`;

The test predicts extremes from the constants and matches each official
high/low to the nearest computed one of the same kind — with deliberately
looser tolerances than the oracle tests, because now the differences are
real (datum rounding, node-correction epoch, constituent-set differences
between NOAA's internal engine and ours):

#expect(timeErr < 15, "\(off.kind) at \(off.time): time off by \(timeErr) min")
#expect(heightErr < 0.15, "\(off.kind) at \(off.time): height off \(heightErr) m")

Result across 12 highs/lows over three days: max time error 7.9 minutes,
max height error 3.5 cm — well inside tide-table tolerance. The ~8-minute
residual is expected and instructive: NOAA's engine uses a different
node-correction epoch and constituent set, so exact agreement with the
authority was never on the table. Two tolerance regimes, two different
claims: 1e-6 says "the port is faithful"; ±15 min/±0.15 m says "the
predictions are real."

The same validation pass confirmed the data path for Canadian waters:
CHS doesn't publish bundled harmonics the way NOAA does, but its IWLS API
serves tide predictions directly — and current predictions for 35+ BC
stations — so Canadian coverage rides the authority's own numbers online
rather than redistributed constituents.

Trim the API before anyone depends on it

Porting layer-by-layer leaves scaffolding: everything was public so the
interim checker could poke at it, and some ported code turned out dead (an
astronomical-speeds derivation the engine never uses — constituent speeds
ship pre-computed in the catalog). The last commit of the phase is a
deliberate audit: delete the dead code, demote the internals, and ship the
smallest surface that does the job —

public struct Station {
    public init(constituents: [HarmonicConstituent], offset: Double = 0)
    public func heights(from: Date, to: Date, step: TimeInterval = 600) -> [TidePoint]
    public func extremes(from: Date, to: Date) -> [TideExtreme]
}

Four public types, two methods. Astro, the catalog, the node-correction
table — all internal. Every symbol you expose during the port is a symbol
you can't rename after someone imports it; the oracle makes the trim safe,
because swift test proves the demotions broke nothing.

Three transferable lessons

An oracle turns a risky port into a mechanical one. Generate golden vectors from the reference per layer, and every divergence is caught at the layer that caused it — sign flips, degree/radian mixups, and value-vs-reference semantic mismatches all surfaced as a single red layer, never as "the tides look slightly wrong."
Generate data catalogs from the source; only port algorithms. The 5,000-line constituent catalog crossed languages as a JSON resource with the hard parts (name parsing, compound decomposition) pre-resolved at codegen time. Data you generate can't be mistranscribed, and regenerating beats re-porting when upstream moves.
Matching the reference isn't the finish line — matching reality is. A faithful port of a wrong reference is still wrong. Close the loop against the authority's published numbers, with honest (looser) tolerances and an explanation for the residual.

The engine is MIT, extracted as the open-source core for offline tide work on
our own boats: slackwater-engine.
If your home waters disagree with it, the fixtures show you exactly which
layer to blame — send a fix.

Bench your own workload before you switch LLM vendors

Bryan Clark — Fri, 07 Aug 2026 00:17:57 +0000

TL;DR: Before migrating our voice boat-agent off Claude Sonnet, we ran the
new GPT-5.6 tiers through the same tool-routing benchmark the incumbent runs:
13 real asks, 74 MCP tool schemas, scored on whether the model calls the right
tools. GPT-5.6 scored 38.5% vs Sonnet's 92.3% on our workload, under our
integration constraints — so no migration. Jump to the numbers.
The transferable part isn't the score, it's the method.

What this is not — read this before the numbers. This is not a model
benchmark, and it says nothing about GPT-5.6's overall quality. It is a narrow,
specific fit-for-workload test: can a candidate model, dropped into our
integration path (an OpenAI-compatible /v1/chat/completions runner, which
forces reasoning_effort: "none" when tools are present — more on that below),
route a voice agent's asks to the right tools across our 74-tool MCP surface?
GPT-5.6's full tool-calling story lives in the Responses API, which our runner
doesn't speak. The result generalizes to nothing beyond "not a drop-in swap for
this system, today." If you take a headline score away from this post, you've
misread it. Take the method.

The temptation

Every time a new flagship model ships, the same question shows up: should we
migrate? The leaderboards look great. The pricing looks great. The blog posts
are glowing.

None of that measures your workload.

Our workload is a voice agent on a boat. The architecture pushes determinism
into code — spoken phrasing is templates, tool results are formatted in the
tool layer, composition happens in composed tools. The LLM's actual job is
narrow: hear an ask, pick the right MCP tool(s), call them with workable
args. "What's the current at Boundary Pass?" must route to
currents.get_gate_current, not to a generic sensor read. That's it. Peak
reasoning is not on the critical path; tool-routing correctness and latency
are.

No public leaderboard scores "routes correctly across our 74 marine MCP tool
schemas." So we built the bench once, and now every candidate model gets the
same 15-minute test before any migration conversation is allowed to continue.

The decision rule

The swap rule is written down as code, not vibes. A candidate replaces the
incumbent only if it's faster and holds correctness within tolerance and is
stable:

def compare(incumbent: Scorecard, candidate: Scorecard, eps: float = 0.05) -> Verdict:
    if candidate.error_rate > 0:
        return Verdict(False, f"candidate not session-stable "
                              f"(error_rate={candidate.error_rate:.2f})")
    if candidate.latency_p50 >= incumbent.latency_p50:
        return Verdict(False, f"candidate not faster "
                              f"(p50 {candidate.latency_p50:.2f}s vs "
                              f"incumbent {incumbent.latency_p50:.2f}s)")
    if candidate.correctness < incumbent.correctness - eps:
        return Verdict(False, f"candidate correctness below tolerance "
                              f"({candidate.correctness:.2f} < "
                              f"{incumbent.correctness:.2f} - {eps})")
    return Verdict(True, ...)

Note what this optimizes: speed at a correctness bar, not peak capability.
We want to be persuaded by a faster model. The voice loop has a <5 s warm-hop
target; the incumbent's p50 is over 8 s. A candidate that's 3× faster and
routes tools correctly wins the slot immediately. The bar is the incumbent's
correctness minus ε, because prose quality is deterministic downstream — the
model only has to string the right tools.

The harness

The bench (python -m poseidon.bench in
naturali-agents) drives a
golden set of 13 asks, each annotated with the expected tool call(s):

{
  "id": "current-boundary",
  "category": "navigator",
  "prompt": "What's the current doing at Boundary Pass?",
  "expected_tools": ["mcp__currents__get_gate_current"]
},
{
  "id": "safe-to-anchor",
  "category": "navigator-multi",
  "prompt": "Is it safe to anchor here tonight given the weather and current?",
  "expected_tools": ["mcp__pilotbook__assess_anchorage"]
}

The incumbent runs through its production backend (the Claude Agent SDK). Any
candidate runs through a flat OpenAI-compatible runner — same asks, same 74
tool schemas exported from the production MCP server config, same
recall-based scoring (did the right tools get called; extra exploratory calls
don't penalize):

# incumbent baseline (SDK backend)
uv run python -m poseidon.bench --model claude-sonnet-4-6

# candidate (any OpenAI-compatible endpoint: hosted or local Ollama)
uv run python -m poseidon.bench --backend openai \
  --base-url https://api.openai.com/v1 \
  --model gpt-5.6-terra --reasoning-effort none \
  --baseline dev/bench-results/2026-07-12-claude-sonnet-4-6.json

The --baseline flag makes the run print the swap verdict directly. One
command, a scorecard, an answer.

What the bench surfaced before it produced a number

The runner was originally built for local Ollama models. Pointing it at a
hosted endpoint broke twice — and both breaks are exactly the kind of
integration detail a real bench surfaces and a leaderboard never will.

1. Hosted endpoints need auth; Ollama had let us be lazy. First run: HTTP

Ollama ignores the Authorization header entirely, so the harness had never sent one. The fix is small and keeps local runs working:

def auth_headers() -> dict[str, str]:
    """Bearer auth for hosted OpenAI-compatible endpoints; empty for local
    (Ollama ignores auth)."""
    key = os.environ.get("OPENAI_API_KEY", "")
    return {"Authorization": f"Bearer {key}"} if key else {}

2. GPT-5.6 rejects function tools on /v1/chat/completions unless
reasoning_effort is "none". With auth fixed, requests carrying our
tools array were rejected until we sent reasoning_effort: "none". Full
reasoning plus tools is a Responses-API feature; on the Chat Completions
surface you pick one. So the payload builder grew a passthrough:

def chat_payload(model, messages, schemas, reasoning_effort=None) -> dict:
    """reasoning_effort is passed only when set — GPT-5.6+ rejects function
    tools unless it's 'none' (full reasoning + tools needs the Responses
    API, which this runner predates)."""
    payload = {"model": model, "messages": messages, "tools": schemas,
               "tool_choice": "auto", "stream": False}
    if reasoning_effort is not None:
        payload["reasoning_effort"] = reasoning_effort
    return payload

That second fix matters for reading the results honestly: it means every
GPT-5.6 number below was produced with reasoning off, because that's the
only mode the OpenAI-compatible surface we integrate against permits with
tools. It's a real constraint of the drop-in path we'd actually deploy — the
same seam a local model or any OpenAI-compatible engine would use — but it is
a constraint, and we recorded it as such.

The numbers

Same day, same 13-ask golden set, same live MCP stack, all three GPT-5.6 tiers
plus a fresh incumbent baseline:

Model	Correctness	Error rate	p50 warm hop	p95	Swap verdict (ε=0.05)
claude-sonnet-4-6 (incumbent)	92.3%	0%	8.62 s	18.23 s	—
gpt-5.6-sol (reasoning none)	38.5%	0%	3.40 s	9.64 s	SWAP=False
gpt-5.6-terra (reasoning none)	38.5%	0%	2.32 s	7.35 s	SWAP=False
gpt-5.6-luna (reasoning none)	46.2%	0%	2.79 s	10.99 s	SWAP=False

Two things are true at once here, and both matter.

Latency is excellent. Every GPT-5.6 tier demolishes our <5 s voice-loop
target that the incumbent misses. Terra's p50 of 2.32 s is the fastest
tool-calling turn we've measured on this workload, cloud or local. If
correctness had held, this would have been an easy swap — that's what the
decision rule is for.

Routing collapsed. The failure isn't a near-miss on a couple of hard asks;
it's qualitative. With reasoning off, all three tiers reach for the generic
mcp__signalk__read_sensor on nearly everything. From the Terra scorecard:

| ask             | expected                              | observed                    |   |
|-----------------|---------------------------------------|-----------------------------|---|
| wind-forecast   | mcp__weather__get_marine_forecast     | mcp__signalk__read_sensor   | ✗ |
| currents-nearby | mcp__currents__currents_near          | mcp__signalk__read_sensor   | ✗ |
| tide-heights    | mcp__currents__get_tide_heights       | mcp__signalk__read_sensor   | ✗ |
| anchorage-near  | mcp__pilotbook__find_anchorages_near  | mcp__signalk__read_sensor   | ✗ |
| safe-to-anchor  | mcp__pilotbook__assess_anchorage      | mcp__signalk__read_sensor   | ✗ |

A wind forecast question answered from a live sensor read. An anchorage
question answered from a sensor read. Eight of thirteen asks on Terra route to
the wrong subsystem the same way; Sol and Luna show the same shape. Direct
single-tool asks ("what's my depth") still land — it's the routing across a
wide tool surface that goes.

We'd seen this exact failure shape before, in small local models — the
generic-over-specific tool grab is what an 8B does under pressure. Seeing it
here says something useful and narrow: whatever makes a model good at
picking one tool out of 74 was, on this surface and in this mode, doing that
work in the part we had to turn off.

The fairness caveat, again

Worth restating at the point of maximum temptation to over-read: the
candidates ran under the constraint the OpenAI-compatible surface imposes
(tools ⇒ reasoning none). GPT-5.6's designed tool-calling path — reasoning
plus tool use — lives in the Responses API, which our runner, and any
drop-in OpenAI-compatible engine seam like ours, doesn't speak. A fair
re-test requires porting the runner to the Responses API. That's real work
with no current payoff, so we recorded it as the retest condition instead of
doing it: if the runner grows a Responses backend, or an OpenAI-compatible
endpoint ships that allows tools with reasoning on, GPT-5.6 gets re-benched.

That's also the honest framing of the whole result: we didn't measure what
GPT-5.6 can do; we measured what it does when dropped into our seam. For a
migration decision, that's the measurement that matters — you migrate onto
your integration path, not onto the vendor's best-case demo path.

Why it matters

The bar is yours, not the leaderboard's. Our agent doesn't need chart-top reasoning; it needs to pick get_tide_heights over read_sensor at 2 a.m. in a voice loop. No public eval scores that. Yours scores whatever your system actually spends the model on — write that down as a golden set and a decision rule while nobody's pressuring you to migrate.
The bench is cheap once it exists. This entire gate — three models, fresh baseline, scorecards, verdicts — was about 15 minutes of wall time and negligible API spend. The two harness fixes above were most of the effort, and they're paid for now.
A bench finds integration truth before migration finds it for you. The Bearer-auth gap and the reasoning_effort constraint surfaced in a 15-minute bench. The alternative was discovering them mid-migration, after the decision was already emotionally made.
Negative results are a deliverable. The verdict lives in a dated scorecard and an architecture decision record. Next time a model ships, the conversation starts from "run the bench," not from scratch.

The harness, golden set, and swap rule are in
naturali-agents —
poseidon/bench/. This came out of building the AI ops layer for an
all-electric charter catamaran, where the conversation engine is a pluggable
part and the tool surface is the product.

The NMEA 2000 paradox has an open-source answer

Bryan Clark — Tue, 04 Aug 2026 16:57:31 +0000

Galvanic Works published The NMEA 2000 Paradox — a sharp problem statement about why boats drowning in data still fail their owners: identical beeps for everything, humans as the monitoring system, alerts that collapse under stress, and vendor lock-in. I agree with essentially all of it. This post is the other half: each failure mode they name, next to the open-source code that already addresses it.

Galvanic Works is a marine-safety startup, and their post is the best short statement of the problem I've seen from anyone, commercial or open source. The line that should be framed on every marine electronics bench:

The boat is sinking: beep-beep. The waste tank is full: beep-beep.

Their catalog of failure modes: identical alerts train sailors to ignore alarms; humans can't monitor dozens of simultaneous data streams, least of all under stress; alerts aren't plain language when it matters; and proprietary gateways and manufacturer apps keep the data locked up. They're building a commercial product around fixing this. I've spent the season building the open-source version — a SignalK-based stack with an AI agent on top — and their post reads like my design doc's problem section. So, receipts.

Identical beeps: severity is data, not a sound

The beep-beep problem isn't a hardware limitation — it's a data-model failure, and SignalK already fixed the model. Every SignalK notification carries an explicit severity state and delivery method:

{
  "path": "notifications.mob",
  "value": {
    "state": "emergency",
    "method": ["visual", "sound"],
    "message": "Man overboard!"
  }
}

normal → alert → warn → alarm → emergency. Once severity is data, nothing downstream ever has to emit the same beep twice. My signalk-ntfy-relay maps it straight onto ntfy push priority, so a sinking boat interrupts your phone's do-not-disturb and a full waste tank does not:

Signal K state	ntfy priority	tag
`emergency`	5 (max)	🆘 `sos`
`alarm`	4 (high)	🚨 `rotating_light`
`warn`	3 (default)	⚠️ `warning`
`alert`	2 (low)	ℹ️ `information_source`
cleared (`normal`)	1 (min)	✅ `white_check_mark`

Two details matter as much as the mapping. The relay edge-triggers — one push when an alarm becomes active, not a repeat while it persists (repetition is how you train people to ignore alarms). And clearing is a first-class event (notifyOnClear), because "the alarm stopped" is information too, and a system that only ever escalates erodes trust.

You are not the monitoring system

Their sharpest observation: humans can't watch dozens of streams, and "during an emergency, our brains become 10 times smaller." Agreed — so don't make the human the monitor. My watchstander is an AI agent with two MCP tools in a loop: signalk-mcp's get_active_alarms pulls every live notification off the bus, and vessel-knowledge-mcp's explain_notification joins each one against the vessel's own equipment registry — so the agent doesn't just relay notifications.electrical.batteries.house.voltage, it knows which battery bank, what chemistry, what the manufacturer's floor is, and what to do about it.

The alarms themselves are plain SignalK zones — declarative thresholds in any path's metadata, set from the admin UI, no code:

{
  "electrical.batteries.house.voltage": {
    "meta": {
      "zones": [
        { "lower": 12.0, "upper": 12.4, "state": "warn",  "message": "House bank low" },
        { "upper": 12.0,                "state": "alarm", "message": "House bank critically low" }
      ]
    }
  }
}

The agent's job starts where the zone ends: triage, explanation, and a spoken sentence — not another beep.

One lesson I learned the hard way belongs in any writeup of this problem: the alarm pipeline itself is a thing that fails, silently, precisely because a healthy boat fires no alarms. I wrote that one up separately — the relay now heartbeats its own delivery path and raises notifications.ntfyRelay.deliveryFailed when the path to your phone goes dark.

Plain language under stress

The stress-communication point is where most builders get it wrong by adding detail. The discipline that works is subtraction. My distress plugins (signalk-dsc, signalk-ais-distress) render a voice-sized message — type, vessel, situation, range and direction from own position, action, and nothing else:

DSC distress alert: vessel Wind Chaser, sinking, 2.3 nautical miles northwest. Monitor channel 16.

No MMSI read aloud. No raw coordinates. No "kn" — units are spoken in full because a stressed human parsing text-to-speech shouldn't decode abbreviations. The full detail (MMSI, coordinates, reported time, transport) goes to the call log and an automatic logbook entry, where detail belongs. The agent's own persona rules enforce the same budget conversationally: three sentences is the norm, because every reply is spoken aloud.

The test for any alert is whether it works for a tired human at 0300. Everything that fails that test still gets captured — just not spoken.

Lock-in: integrate, don't replace

Their fourth complaint — expensive gateways, manufacturer-specific apps, PGN translation configured per vendor — is the one the open-source world solved most thoroughly, because it's the reason SignalK exists. The server sits beside the existing electronics as one more bus citizen: NMEA 2000 and 0183 in, one open JSON data model out, every vendor's PGNs normalized to the same paths. Nothing gets replaced; the chartplotter keeps working; the data stops being captive.

To be fair to the hardware reality: you still need a physical bus interface (a CAN adapter or Pi HAT, tens of dollars, not hundreds) — the open stack removes the software toll, which is where the lock-in actually lives. Every piece named in this post is MIT-licensed and on npm under @sailingnaturali; the alarm model and zones are stock SignalK.

The gap they're right about

One item in their post names something the open stack genuinely doesn't have: trend analytics over accumulated history — battery degradation curves, maintenance forecasting from engine metrics. The storage half exists (SignalK-to-InfluxDB is mature), but the analysis layer — "your house bank has lost 11% capacity since spring, book a load test" — is unbuilt in the open as far as I can tell. That's a real gap, it's the kind of thing a commercial player may well do first, and I'd love to be wrong about nobody having built it. If you have, say so.

Where this lands

Full disclosure: my boat is ashore, and most of what this server reports is a mocked vessel on a bench.

The RF half, though, stopped being hypothetical while this post sat in draft. A VHF receiver went onto the bench rig in late July, and real AIS is now flowing into SignalK from it — live targets, real MMSIs, actual traffic moving around the harbour. (The first read was structured garbage. The RS422 differential pair was reversed; the fix was swapping two wires, after a couple of hours of blaming the baud rate.) Position still comes from the mock, because a radio indoors has no sky view, and the DSC watch hasn't had its live soak test yet. So the alarm plumbing above is working code against real radio traffic — and still not sea miles.

But that's rather the point of doing it in the open. Galvanic Works wrote an excellent diagnosis and is building their answer as a product; I'm building mine as a pile of MIT-licensed SignalK plugins and MCP servers anyone can install tonight. Boats get safer both ways, and the more people naming the beep-beep problem out loud, the fewer identical beeps get shipped. Diagnosis fully endorsed — here's the source.

MCP server or a curl recipe in AGENTS.md? Measure the breakeven

Bryan Clark — Sun, 02 Aug 2026 15:30:03 +0000

The current consensus is that MCP is a token tax and you should just tell the agent to curl the API from its AGENTS.md. I measured both, for the same capability, against the same server. The tool schemas cost +408 tokens standing and save ~340–420 tokens per read, so the breakeven is roughly one tool call per turn — and with prompt caching (measured, not assumed: a 0.175× effective multiplier across 3,782 real requests) it moves to one read every five or six turns. But the tokens are the easy half and they nearly cancel. What actually decided it was a minus sign. Jump to the breakeven formula.

There's a good argument going around that MCP servers are a context-window tax — tool schemas at ~550–1,400 tokens each, benchmarks putting MCP at 4–32× the token cost of an equivalent CLI, a spec issue open on the overhead itself. The conclusion people draw is: skip the server, describe the API in your agent file, let the model shell out.

I have the same capability implemented both ways, so I measured it instead of arguing about it.

Two ways to let an agent read a boat

The job: an agent that can answer "how much water under the keel?" and "how's the house bank?" from a SignalK server — the open marine data server that normalises NMEA 2000/0183 into one JSON tree.

Option A — an MCP server. signalk-mcp exposes seven named tools. The schemas sit in the prompt every turn:

types.Tool(
    name="depth_state",
    description=(
        "Use this for 'what's our depth?' / 'how much under the keel?' / "
        "'how close are we to running aground?' — returns water depth with "
        "under-keel clearance first. below_keel_m IS the clearance under the "
        "hull (no draft math needed). Do NOT read depth via read_sensor: the "
        "raw transducer path (environment.depth.belowTransducer) is NOT "
        "under-keel depth and will mislead. Do not guess depth paths or "
        "compute clearance yourself; call this."
    ),
    inputSchema={"type": "object", "properties": {}},
),

Seven of those: get_active_alarms, read_sensor, get_route, battery_state, depth_state, get_local_time, list_paths.

Option B — a prose recipe in the agent file. No server, no schemas. The agent gets shell access and a section in its always-on AGENTS.md:

## Reading the boat (SignalK)

Boat data lives in SignalK on `http://localhost:3000` (anonymous reads, no auth).
Use the exec tool with `curl`. `jq` is available for filtering.

- One value: `curl -s http://localhost:3000/signalk/v1/api/vessels/self/<path> | jq '.value'`
  where the SignalK dotted path becomes slashes.
- A whole group at once (fewer calls):
  `curl -s http://localhost:3000/signalk/v1/api/vessels/self/electrical | jq`
- Top-level groups: `navigation`, `environment`, `electrical`, `propulsion`,
  `tanks`, `watermaker`, `communication`, `design`, `notifications`.
- **Units are SI:** speed m/s, angles **radians**, depth meters, temperature
  **Kelvin**. Convert for the Captain — knots, degrees, °C.
  (m/s→kn ×1.94384; rad→deg ×57.2958; K→°C −273.15.)
- **Battery current sign: positive = charging** (Victron convention).
- History (`/signalk/v2/history/…`) is not available — answer "now."
- **Never fabricate.** If curl fails or a path is missing, say so.

Both are always-on. Both answer the same questions. Now the receipts.

Round 1 — standing cost, the part everyone measures

This is what you pay every turn, including turns where nobody asks about the boat.

	tokens/turn
MCP: seven tool schemas	874
Agent file: the SignalK section	466
Δ — agent file wins	−408

How I counted — tiktoken, cl100k_base, pulling the tool definitions straight out of the source with ast so there's no hand-transcription:

import ast, tiktoken
enc = tiktoken.get_encoding("cl100k_base")
src = open("src/signalk_mcp/server.py").read()
tools = [{kw.arg: ast.literal_eval(kw.value) for kw in node.keywords}
         for node in ast.walk(ast.parse(src))
         if isinstance(node, ast.Call)
         and getattr(node.func, "attr", None) == "Tool"]
print(len(enc.encode(open("AGENTS.md").read())))

One honest note on the 874: that's the _list_tools() definition block as written. Serialised to JSON it's 845; namespaced the way a client renders it (mcp__signalk__depth_state) it's 887. So call it 845–890 depending on your client — the spread doesn't move anything below.

So far the MCP-is-a-tax crowd is right. 408 tokens a turn, forever, is a real cost.

Round 2 — the part the benchmarks skip

The CLI benchmarks usually stop at the schema. But a tool call has a result, and the result also lands in the context window.

Here is what curl gets back for depth — the whole reason the recipe exists:

{
    "transducerToKeel": {
        "meta": {
            "description": "Depth from the transducer to the bottom of the keel",
            "units": "m",
            "displayUnits": {
                "category": "depth",
                "targetUnit": "m",
                "formula": "value",
                "inverseFormula": "value",
                "symbol": "m",
                "displayFormat": "0.0"
            }
        },
        "value": -1.12,
        "$source": "defaults",
        "timestamp": "2026-08-01T13:35:02.076Z"
    },
    "surfaceToTransducer": { ...same meta block again... },
    "belowTransducer":     { ...same meta block again... },
    "belowKeel":           { ...plus alarmMethod, warnMethod, three zones... },
    "belowSurface":        { ...same meta block again... }
}

515 tokens, of which the five value fields are about a dozen. Everything else is meta — description, units, and a displayUnits object carrying formula, inverseFormula, symbol and displayFormat — repeated per leaf. The agent pays for all of it and then has to find the numbers inside.

The MCP tool returns this instead:

{
  "below_keel_m": 36.42532195742289,
  "below_surface_m": 37.795321957422885,
  "below_transducer_m": 37.545321957422885,
  "display": "36.4 metres under the keel, 37.8 metres total depth",
  "timestamp": "2026-08-01T18:37:26.629Z"
}

92 tokens. Same numbers, plus a TTS-safe sentence the voice pipeline can read out verbatim.

read	raw `curl` response	MCP tool result	ratio
`environment/depth`	515	92	5.6×
`electrical`	431	93	4.6×
`navigation`	627	~92	6.8×

You can't jq your way out of most of this, either. Piping to jq '.value' works for a single leaf, but the recipe's own advice — grab the whole subtree in one call to save round trips — is exactly the case where the meta bloat arrives in full.

The breakeven formula

Two levers pulling opposite directions. Set them against each other.

Let ΔS = the standing-cost difference (schemas − prose) and ΔR = the per-read saving (raw response − tool result). Cost per turn at k reads:

agent file:   P + k · raw
MCP server:   S + k · tool

MCP is cheaper when   S + k·tool  <  P + k·raw
                             k    >  (S − P) / (raw − tool)
                             k*   =  ΔS / ΔR

For this pair: k* = 408 / ~400 ≈ 1.02 reads per turn.

That's the finding. Not "MCP good" or "MCP is a tax" — it pays for itself at roughly one tool call per turn.

Which cuts cleanly in both directions:

A general-purpose agent that touches the boat on one turn in twenty: the agent file is cheaper, and it isn't close.
An agent whose entire job is the boat, where essentially every turn is a read: the MCP wins outright.

My constants aren't yours. Run the same three measurements on your own server — schema tokens, prose tokens, and a representative raw-vs-tool response pair — and divide. If your API returns lean JSON, ΔR collapses and the prose recipe wins at almost any k. If your API is as metadata-heavy as SignalK's, ΔR is large and k* drops below 1.

Prompt caching moves k*, and I measured by how much

The standing cost is the MCP's only loss — and it's the exact part that caches. Tool schemas are a stable prefix. The per-read saving is on churny tokens that never cache. So caching should shrink ΔS and leave ΔR alone, which moves k* down.

The tempting shortcut is to call cached tokens "10% of input" and be done. That's wrong, because it only counts the read side. A cache entry has to be written first, and writes cost more than uncached input.

So rather than assume a hit rate, I aggregated the usage field across the 40 most recent agent session transcripts for this project — 3,782 billed requests on a real runtime with signalk-mcp attached:

cache READ    698,670,375 tokens   94.33% of input-side
cache WRITE    41,945,413 tokens    5.66%
uncached input     29,139 tokens    ~0.00%

cold requests (zero cache read):  150 / 3,782  =  4.0%

Every write in that sample was 1-hour TTL (ephemeral_1h_input_tokens; ephemeral_5m was zero), which matters — the price multiplier depends on TTL. Per the prompt-caching docs: cache read 0.1× base input, 5-minute write 1.25×, 1-hour write 2×.

A standing block gets written on cold turns and read on warm ones, so its effective multiplier is cold × write + warm × read:

	measured
cold turns	4.0%
warm turns	96.0%
standing-block effective multiplier (1h TTL — what we ran)	0.175×
the same block at 5-minute TTL	0.146×
blended multiplier across all input-side tokens	0.208×

Apply that to the 408-token standing delta and re-run the formula:

408 × 0.175  =  ~72 effective tokens

k* = 72 / 400  ≈  0.18 reads per turn

About one boat read every five or six turns. Not the one-in-ten you get from the flat-10% shortcut — the write side is the expensive half and at 1-hour TTL it costs 2×.

Caching still makes the MCP case stronger, just less dramatically than the naive math suggests. And it's conservative in the MCP's favour for a second reason the formula doesn't capture: a tool result is uncached only on the turn it arrives. After that it joins the cached prefix at 0.175× for the rest of the session. The ~400-tokens-per-read saving counts only the first turn; the MCP's leaner results keep paying rent afterwards.

Three things to be honest about before you reuse the 0.175×:

That's a hot session. 96% warm is what sustained back-to-back work produces. A boat agent DM'd over Telegram with minutes between messages cold-starts far more often — the 5-minute TTL expiring between turns is a problem I've hit before. So 0.175× is the favourable end. A bursty agent lands nearer the uncached case — which widens the MCP's advantage rather than narrowing it: the standing penalty grows back toward 408, but so does the value of never re-sending 500-token blobs.
Runtime attribution: these are Claude Code sessions carrying the MCP, not the boat agent itself. Real cache behaviour of a real agent holding these schemas — but I didn't instrument the boat agent, and I'm not claiming I did.
The 1-hour TTL is a property of this session, not a universal default. On the 5-minute default the multiplier is 0.146× and the standing penalty is ~59 tokens, a slightly cheaper MCP.

One takeaway for reading other people's numbers: the MCP-vs-CLI benchmarks I can find quote schema cost uncached. On this measured multiplier that overstates the standing penalty by about 5.7×.

The half that tokens don't measure

Here's the thing that actually decided it, live off the boat's environment.depth tree:

environment.depth.belowTransducer   =  38.5187
environment.depth.transducerToKeel  =  -1.12      <-- stored NEGATIVE

The keel offset is stored as a negative number. Under-keel clearance is therefore an addition:

belowTransducer + transducerToKeel  =  38.5187 + (-1.12)  =  37.40 m   ✅

An agent reading the raw tree and doing the obvious thing — depth below the transducer, minus the keel offset — gets:

38.5187 - (-1.12)  =  39.64 m   ❌

It reports 2.24 metres more clearance than the boat actually has, and the error points toward grounding. In 38 m of water that's a rounding error. In 3 m it's the whole margin, delivered in a confident voice.

Nothing in the token comparison sees this. The wrong answer costs the same as the right one.

The MCP does the arithmetic in Python, where it can't be dropped:

below_keel = below_keel_obj.get("value")   # SignalK's own belowKeel leaf
...
"display": _depth_display(below_keel, below_surface, below_transducer),

— and the tool description spends tokens specifically to stop the model freelancing: "Do NOT read depth via read_sensor: the raw transducer path is NOT under-keel depth and will mislead. Do not guess depth paths or compute clearance yourself; call this." That instruction is part of the 874. It's not schema bloat; it's the thing being bought.

What the prose recipe is really asking for

Look back at the agent file with this in mind. Every bullet is a rule the model has to remember and apply by hand, on every read, forever:

m/s → knots          × 1.94384
radians → degrees    × 57.2958
Kelvin → °C          − 273.15
battery current      positive = charging (Victron convention)

Four conversions, plus a sign convention, plus the keel-offset sign that isn't even in the list because nobody thought to write it down. Each is a coin flip on a bad turn — a long context, a distracting question, a smaller model. And the failure is silent: the model returns a number, not an error. "38 degrees" when the value was radians reads perfectly plausibly.

In Python those are five lines that execute the same way every time:

if tail in _SPEED_KEYS:
    return f"{value * 1.94384:.1f} knots", "knots"
if tail in _BEARING_KEYS:
    deg = math.degrees(value) % 360
    return f"{deg:.1f}° ({_degrees_to_compass(deg)})", "°"
if tail == "temperature":
    return f"{value - 273.15:.1f}°C", "°C"

So the summary is: the agent file is cheaper to carry and more expensive to be wrong with. The token comparison is the easy half and it nearly cancels. The deciding factor is where the domain knowledge lives — in prose the model may skip, or in code it can't.

Caveats, before you quote my numbers

The vessel is ashore. This is Phase 0; the SignalK server runs a mock vessel plugin. The token counts, response shapes and the transducerToKeel sign convention are all real. The readings are synthetic — nobody is in 38 m of water off Boundary Pass right now.
cl100k_base is a proxy. Your model's tokenizer will give slightly different numbers. The ratios hold; the absolutes won't.
874 vs 466 is my seven-tool server against my recipe. The formula generalises. The constants absolutely do not.
This is not a controlled A/B. The two setups differ in more than MCP-vs-file — different runtimes, Python vs curl. It's a like-for-like cost comparison of two ways to give an agent the same capability, not a single-variable experiment.

Where it lands

I kept the MCP server, and the reason isn't the tokens — on tokens it's a coin flip that caching tips slightly my way. I kept it because depth_state cannot get the sign wrong, and a prose bullet can.

The rule of thumb I'd offer: compute k* = ΔS / ΔR before you argue about it, and then ask the question the tokens can't answer — is there any arithmetic in this domain that the model must not get wrong? If yes, that decides it regardless of which side of the breakeven you land on.

The server is signalk-mcp (MIT), part of the agent stack I'm building for an all-electric charter catamaran that doesn't exist yet.

Related: Why we kept named MCP tools despite a 96% token saving — the same tradeoff one level down, inside the MCP server; Running OpenClaw on a Raspberry Pi alongside SignalK — where the curl recipe comes from, plus AGENTS.md vs SKILL.md measured the same way; and Why your agent ignores its skill body but obeys the system prompt — always-on vs conditional, the first axis of this question.

A persistent-queue HTTP reporter for distress traffic over flaky internet

Bryan Clark — Sat, 01 Aug 2026 16:05:03 +0000

TL;DR — Don't fetch()-and-forget safety-relevant reports over marine internet. signalk-distress-core ships a generic persistent-queue HTTP reporter: every payload is appended to a JSONL file before the POST, delivered sequentially in order, retried forever on network errors, retried with a cap on 5xx, and dropped immediately on 400/404. The queue survives crashes and restarts. Jump to the response policy.

Why this matters for safety at sea

When a vessel in trouble hits the red distress button on a DSC VHF radio — or an EPIRB, SART, or MOB beacon starts transmitting on AIS — every receiver in range gets a copy. Shore stations hear most of it. But VHF is line-of-sight: behind an island, deep in a fjord, or simply far enough offshore, a distress burst can be heard by a nearby boat and missed by every shore station. The copy your radio captured may be the only one with a position in it that made it anywhere.

That's the case for relaying received distress traffic to a shore-side aggregation service: a crowd of receivers extends coverage beyond what any single station — afloat or ashore — can hear. DSCWatch is one such network: it aggregates received DSC traffic from stations around the world into coverage maps and distress logs, and signalk-dsc can submit every call it hears.

But now look at the chain: radio → boat server → boat internet → aggregation service. On a boat, the uplink is the least reliable link in that chain. Cellular dies in exactly the remote places where your copy of a distress call matters most. Satellite drops in rain, in swell, behind terrain. The server power-cycles with the house bank. If the reporting code is a bare fetch(), every one of those blinks silently discards a heard distress call — and "we dropped a MAYDAY on the floor because the internet blinked" is not an acceptable failure mode.

So the delivery requirements write themselves:

Write-through persisted — the report is on disk before the first delivery attempt, so a crash mid-flight loses nothing.
Restart-proof — whatever was undelivered at shutdown is delivered after startup.
In-order — DSC position refinements ($--DSE) must arrive after the alerts they refine.
Offline catch-up — hours of outage queue up and drain when connectivity returns.

That's a generic problem, not a DSC problem. So it lives in signalk-distress-core (v0.5.0) as a payload-agnostic module — signalk-dsc maps its events onto DSCWatch report bodies and calls report(); signalk-ais-distress can reuse it as-is. The rest of this post is the engineering.

The naive versions, and why each one fails

Fire-and-forget is where everyone starts:

// Looks fine on shore wifi. On a boat it's a data shredder.
fetch(url, { method: 'POST', body: JSON.stringify(report) }).catch(() => {});

Offline for six hours crossing a strait? Six hours of received calls are gone. Process restarts? Anything in flight is gone. And on a boat both of those are routine, not exceptional.

Retry in memory is the next instinct — keep an array, retry on failure:

const queue = [];
function report(payload) { queue.push(payload); flushSoon(); }

Better, until the process exits — SignalK restarts whenever you save any plugin's configuration, and the whole server power-cycles with the boat's electrical system. Everything queued is gone.

Batch to disk on a timer is the classic telemetry answer: buffer, flush every N seconds. But the window between "received" and "persisted" is exactly the crash window, and for distress traffic the acceptable size of that window is zero.

Write-through, not batching

The reporter appends the payload to a JSONL queue file first, then immediately kicks the flusher. A healthy network still sees the POST within milliseconds; the disk write just happens to come before it.

return {
  /** Enqueue and kick the flusher. Fire-behind: never throws. */
  report(payload) {
    try {
      queue.push({ payload, attempts: 0 });
      if (queue.length > maxQueue) {
        queue = queue.slice(-maxQueue);
        persist();
      } else {
        fs.mkdirSync(path.dirname(queueFile), { recursive: true });
        fs.appendFileSync(queueFile, JSON.stringify(payload) + '\n');
      }
      flush();
    } catch (err) {
      log(`reporter: enqueue failed: ${err.message}`);
    }
  },
  start() { started = true; flush(); },
  stop()  { started = false; clearTimeout(timer); timer = null; },
};

Three deliberate choices in those few lines:

appendFileSync, one JSON object per line. Append is the cheapest durable write there is, and JSONL means a partial write corrupts one line, not the file (more on that below).
Fire-behind, never throws. The caller is a hot path handling a distress alert — raising alarms, writing the logbook. Reporting must never take that path down.
attempts is in-memory only. The disk format is just payloads. Retry accounting resets on restart, which is fine — a restart is a fresh chance, not a continuation of a grudge.

Delivery is sequential and in order — one POST at a time, head of the queue first — so a $--DSE position refinement can never overtake the distress alert it refines.

The response policy: what each HTTP answer means

The core design decision is that "the POST failed" is three different situations, and each one gets a different answer:

Outcome	Meaning	Action
`2xx`	Delivered (200 merged / 201 created)	Dequeue, persist, reset backoff
`400` / `404`	Bad body or rejected receiver key — a retry cannot fix it	Drop it, move on (404 also signals the plugin once)
`5xx`	Server reachable but erroring	Retry with backoff, capped per entry
Network error / timeout	Offline — the marine normal	Keep everything, back off, catch up later

Here's the flush loop that implements it:

async function flush() {
  if (!started || flushing) return;
  flushing = true;
  try {
    while (started && queue.length) {
      const entry = queue[0];
      let res;
      try {
        res = await fetchImpl(url, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json', 'User-Agent': userAgent },
          body: JSON.stringify(entry.payload),
          signal: AbortSignal.timeout(fetchTimeoutMs),
        });
      } catch (err) {
        // Network down (the offline-passage case): keep everything —
        // whatever is behind the head is failing for the same reason,
        // so in-order blocking costs nothing. Retry on a growing timer.
        if (!started) return;
        log(`reporter: network error (${err.message}) — ${queue.length} queued`);
        backoff();
        return;
      }
      if (!started) return;
      if (res.ok) {
        queue.shift();
        persist();
        backoffMs = backoffBaseMs;
        permanentSignaled = false;
        continue;
      }
      if (res.status === 400 || res.status === 404) {
        // A retry cannot fix a bad body or a rejected receiver key.
        queue.shift();
        persist();
        log(`reporter: dropped report (HTTP ${res.status})`);
        if (res.status === 404 && !permanentSignaled) {
          permanentSignaled = true;
          onPermanentError(res.status);
        }
        continue;
      }
      // Server reachable but erroring (5xx): retry with backoff, but cap
      // per entry — one poison payload must not block the queue behind it.
      entry.attempts += 1;
      if (entry.attempts >= maxAttempts) {
        queue.shift();
        persist();
        log(`reporter: dropped report after ${maxAttempts} attempts (HTTP ${res.status})`);
        continue;
      }
      backoff();
      return;
    }
  } finally {
    flushing = false;
  }
}

The asymmetry is the point:

Network errors never consume retry attempts. Being offline for a nine-hour passage is not the payload's fault, so nothing is dropped for it, ever (up to maxQueue). Head-of-line blocking is free here — everything behind the head would fail for the same reason.
5xx retries are capped per entry (maxAttempts, default 10). Without the cap, one poison payload that reliably 500s would block every report behind it forever. With it, in-order delivery yields to liveness after a bounded effort.
400/404 are dropped on the first response. A malformed body or an unknown receiver key will be exactly as malformed on attempt fifty. Retrying a permanent rejection just hammers someone else's server.
404 signals the plugin exactly once (onPermanentError → app.setPluginStatus in signalk-dsc), and a later success resets the once-guard. Reports keep being attempted, so fixing the receiver key or the endpoint URL in config heals delivery without a restart — no "notification spam" and no "silently wedged until reboot".

That last point is the same lesson as our ntfy 401 incident: a delivery path that fails must say so somewhere a human looks, exactly once, and recover by itself when the config is fixed.

Surviving restarts: reload, torn lines, and the trim

On construction the reporter reloads whatever the last process left behind:

try {
  for (const line of fs.readFileSync(queueFile, 'utf8').split('\n')) {
    if (!line.trim()) continue;
    try {
      queue.push({ payload: JSON.parse(line), attempts: 0 });
    } catch {
      // torn/corrupt line — skip it, keep the rest
    }
  }
} catch {
  // no queue yet
}

The torn-line skip is why the disk format is JSONL and not one big JSON array: if the power died mid-append, exactly one line is unparseable. JSON.parse per line means that line is skipped and every intact report before and after it still delivers. A JSON array with a torn tail would lose the whole file.

Rewrites (dequeue, trim) go through a temp-file-and-rename persist() so the queue file is never observed half-written:

function persist() {
  const tmp = `${queueFile}.tmp`;
  fs.mkdirSync(path.dirname(queueFile), { recursive: true });
  fs.writeFileSync(tmp, queue.map((e) => JSON.stringify(e.payload)).join('\n') + '\n');
  fs.renameSync(tmp, queueFile);
}

And maxQueue (default 5000) drops oldest first when a long outage overflows it. Newest-wins is the right policy for distress relay: the most recent calls are the ones a shore-side service can still act on, and 5000 queued reports is weeks of traffic for most stations anyway.

The bug that shipped in v0.5.0: the stale-flusher restart race

v0.5.0 shipped with the design above and a green test suite — and a race that could destroy the queue file. It was caught the same morning, reviewing the shutdown path, and fixed in v0.5.1.

The scenario: SignalK restarts a plugin whenever its configuration is saved. That calls stop() on the old reporter instance and constructs a new one — which loads the queue file and starts appending to it. But stop() can land while the old instance's POST is still in flight. The old flusher is parked on await fetchImpl(...). When that stale fetch finally resolves:

// v0.5.0 — the resolving await charges ahead:
if (res.ok) {
  queue.shift();
  persist();   // rewrites the queue file from the OLD instance's memory
  ...

persist() rewrites the whole file from the old instance's in-memory queue — silently deleting every report the new instance had appended since. A config tweak at the wrong millisecond erases a heard distress call from the queue. Exactly the failure mode this module exists to prevent, reintroduced by its own cleanup path.

The fix is two guards — re-check started after every await boundary before touching shared state:

      } catch (err) {
        // Network down ...
+       if (!started) return;
        log(`reporter: network error (${err.message}) — ${queue.length} queued`);
        backoff();
        return;
      }
+     if (!started) return;
      if (res.ok) {
        queue.shift();
        persist();

The catch-branch guard matters too: without it, a network error resolving on a stopped reporter schedules a fresh backoff timer — a zombie instance that wakes up later and races the live one.

Two consequences worth naming:

The in-flight entry stays queued for the new instance, so it may be POSTed twice. That's deliberate: the DSCWatch backend deduplicates repeated submissions of the same call (DSC alerts auto-repeat on air anyway, and every repeat is reported), so at-least-once is the correct choice over at-most-once. For distress traffic, a duplicate is noise; a loss is the failure.
This is the generic async shutdown lesson, nothing marine about it: any await in a loop is a suspension point where the world can change — including "you were stopped and replaced". Every resumption that mutates shared state (a file, a socket, a DB row) has to re-validate that it still owns that state.

And the race got a test — a gated fetch that holds the POST in flight across a stop():

test('stop() during an in-flight POST: the stale flusher never touches the queue file', async () => {
  const queueFile = tmpQueue();
  let resolveFetch;
  const gate = new Promise((r) => (resolveFetch = r));
  const impl = async (url, opts) => {
    calls.push(JSON.parse(opts.body));
    await gate; // hold the POST in flight
    return { ok: true, status: 201 };
  };
  const reporter = createReporter({ url: 'u', userAgent: 'ua', queueFile, fetchImpl: impl });
  reporter.start();
  reporter.report({ seq: 0 });
  await eventually(() => assert.equal(calls.length, 1)); // fetch is in flight
  reporter.stop(); // plugin restart: a new instance may now own the file
  fs.appendFileSync(queueFile, JSON.stringify({ seq: 99 }) + '\n'); // new instance's append
  resolveFetch(); // stale POST finally resolves
  await new Promise((r) => setTimeout(r, 50));
  const onDisk = fs.readFileSync(queueFile, 'utf8').trim().split('\n').map((l) => JSON.parse(l).seq);
  assert.deepEqual(onDisk, [0, 99]); // stale flusher must NOT have shifted/persisted
});

Fetch timeouts: a black-holed link must not wedge the flusher

v0.5.1 also added the one thing a default Node fetch won't give you — a deadline:

res = await fetchImpl(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'User-Agent': userAgent },
  body: JSON.stringify(entry.payload),
  signal: AbortSignal.timeout(fetchTimeoutMs),   // default 30 s
});

Marine links don't just go down — they black-hole: a satellite terminal that accepts the TCP connection and then says nothing more, sometimes for minutes. Without a timeout, the single sequential flusher sits parked on that await indefinitely, and the whole queue stalls behind a connection that will never answer. AbortSignal.timeout() (stdlib since Node 17.3, no AbortController boilerplate needed) turns that into an abort error, which takes the existing network-error path: keep the entry, back off, retry.

Tests pin the policy, not the implementation

The response policy is the contract, so the tests assert it directly against a scriptable fetch stand-in — no HTTP server, no mocking framework, just node:test:

test('400 is dropped without retry; the next report still delivers', async () => {
  const { impl, calls } = mockFetch((call) =>
    call.body.bad ? { ok: false, status: 400 } : { ok: true, status: 201 }
  );
  const reporter = createReporter({ url: 'u', userAgent: 'ua', queueFile: tmpQueue(), fetchImpl: impl });
  reporter.start();
  reporter.report({ bad: true });
  reporter.report({ good: true });
  await eventually(() => {
    assert.equal(calls.length, 2); // bad tried exactly once
    assert.equal(calls[1].body.good, true);
  });
  reporter.stop();
});

test('5xx retries are capped per entry, then the entry drops and the queue moves on', async () => {
  const { impl, calls } = mockFetch((call) =>
    call.body.poison ? { ok: false, status: 500 } : { ok: true, status: 201 }
  );
  const reporter = createReporter({
    url: 'u', userAgent: 'ua', queueFile: tmpQueue(), fetchImpl: impl,
    maxAttempts: 3, backoffBaseMs: 5, backoffMaxMs: 10,
  });
  reporter.start();
  reporter.report({ poison: true });
  reporter.report({ after: true });
  await eventually(() => {
    const poisonTries = calls.filter((c) => c.body.poison).length;
    assert.equal(poisonTries, 3); // exactly maxAttempts, then dropped
    assert.equal(calls[calls.length - 1].body.after, true);
  });
  reporter.stop();
});

The full suite pins every row of the policy table: 200-and-201 both accepted, in-order delivery, offline catch-up resuming in order with nothing dropped, restart recovery from the JSONL file, torn-line skip, maxQueue oldest-first trim, the 404 signal-once-reset-on-success behaviour, and the stale-flusher race above. fetchImpl is injectable for exactly this reason — the only seam the module needs.

Two small design notes riding along in the same release:

The receiver key is minted once and persisted (loadOrCreateReceiverKey): DSCWatch has no registration call — the first report for a new key creates the receiver record — so the only rule is reuse the same value forever. A UUID written to a file in the plugin data directory does that; a station that wants attribution can configure its own key instead.
What leaves the boat is a pick-list, not a filter. The report builder in signalk-dsc copies an explicit allow-list of parsed call fields; local-only data (own-ship weather snapshots, spoken alert text, internal IDs) is never sent because it is never picked. Privacy boundaries built as "copy what's allowed" don't rot the way "strip what's forbidden" does. Reporting is on by default with a single toggle to keep all data on the boat — see the plugin README for the exact field list.

Gotchas if you build one of these

Append-before-POST, always. If the durable write isn't strictly first, there is a crash window, and on a boat the crash window gets hit.
Classify responses; don't treat "not ok" as one case. Permanent rejections (400/404) retried forever are abuse; transient errors (5xx, timeouts) dropped immediately are data loss. The policy needs both, explicitly, with tests.
Cap retries per entry, not globally. The cap exists to defeat poison-payload head-of-line blocking; a global cap would let one bad payload spend the whole budget.
Re-check ownership after every await. stop() + in-flight I/O + shared file = the stale-flusher race. Guard every resumption that touches shared state.
timer.unref() the backoff timer so a pending retry never keeps the host process alive past shutdown.
JSONL over a JSON array for any on-disk queue: torn writes cost one record, not the file.

Close

This runs on the same all-electric-catamaran SignalK stack as the rest of this blog, relaying what the radio hears toward people who can use it. The reporter is payload-agnostic and MIT-licensed: @sailingnaturali/signalk-distress-core (lib/reporter.js, ~180 lines, tests included), consumed by signalk-dsc for DSCWatch reporting.

Related: how the DSC calls get captured in the first place — Logging VHF DSC distress calls in SignalK (PGN 129808) — and the delivery-path-monitoring lesson this reporter inherits — Monitor the delivery path, not just the alarm.

Offline tidal currents from harmonic constituents — and when not to trust them

Bryan Clark — Fri, 31 Jul 2026 16:05:43 +0000

TL;DR — signalk-currents v0.7.0 keeps publishing tidal-current predictions when the boat loses internet: it bundles public-domain NOAA harmonic constituents and synthesizes slack/flood/ebb events offline with Neaps. But every fallback reading is labeled source: "harmonic", live: false, and — at constricted passes — unreliableForTransit: true, because harmonic slack timing at a tidal rapids can be off by tens of minutes. While the network is up, the plugin logs harmonic-vs-live discrepancies locally so the error is measured, not guessed. Jump to the build.

Marine software has one non-negotiable requirement that most connected software gets to ignore: it has to keep working when the internet doesn't. A tidal-currents plugin that answers "when is slack at the pass?" only while the LTE link is up is worse than a paper tide book — because you'll have built your habits around asking it.

This post is the deeper look promised in the signalk-currents README: how the offline harmonic fallback works, why it deliberately announces its own unreliability at constricted passes instead of silently degrading, and how it measures itself against live data while it still can.

Problem

signalk-currents publishes environment.current and a /currents resource by fetching live predictions from the CHS (Canada) and NOAA (US) tides-and-currents APIs, one fetch per station per UTC day. Every poll needs connectivity. Kill the uplink and the failure looks like this in the server log:

signalk-currents: station Seymour Narrows live fetch failed: fetch failed
signalk-currents: station Boundary Pass live fetch failed: fetch failed

The per-day cache papers over short outages — per-day predictions are immutable, so anything already fetched keeps serving — but it's an in-memory Map scoped to the process. Restart the server while offline, or sail past the configured horizonDays, and currents go dark. On a boat, "restart while offline" is not an edge case; it's Tuesday.

What we tried (and why it failed)

Attempt 1: just serve the cache harder. Persist the day cache to disk, fetch a longer horizon. This helps (and is a good idea anyway), but it's not synthesis — it can never answer beyond the last fetched day, and it does nothing for a station you never fetched. A cache is a memory, not a model.

Attempt 2: bundle harmonic constituents for every gate. This is the obvious move: tide clocks have synthesized predictions from harmonic constituents for a century, entirely offline. It works — for exactly half the cruising ground:

NOAA (US) current constituents:  public domain, freely redistributable ✓
CHS (Canada) current constituents: not redistributable ✗

CHS harmonic constants are licensed non-commercial, non-redistributable, and not-for-navigation — you cannot ship them in an MIT-licensed npm package. And the Salish Sea's strong narrows — Seymour, Dodd, Gillard, Dent, Arran, Active, Porlier — are all CHS waters. The licensing wall lands precisely on the stations that matter most.

Attempt 3: WebTide. DFO's WebTide model has Salish-wide current constituents, but it's Crown copyright (redistribution needs written permission) and carries only 8 constituents with no shallow-water overtides — and overtides are exactly what constricted channels need (more on that below).

So v1 bundles what's legal: nine public-domain NOAA current stations covering the US Salish passes — Deception Pass, Rosario Strait, Admiralty Inlet, San Juan Channel, Haro Strait (two bins), Guemes Channel (two bins), and Boundary Pass. The Canadian rapids stay API-only, and the plugin says so out loud rather than pretending otherwise.

The build

A tide-height engine, repurposed for currents

There was no currents-capable harmonic synthesis library on npm. But Neaps (@neaps/tide-predictor, MIT) does the hard part — the astronomical argument and node-factor machinery behind summing constituents — for tide heights. The trick: Neaps doesn't care what the scalar is. Feed it amplitudes in knots instead of meters and its "water level" is the signed major-axis current velocity. Positive level = flood, negative = ebb, zero crossing = slack:

// src/sources/harmonic.ts
export function synthesizeEvents(hs: HarmonicStation, start: Date, end: Date): CurrentEvent[] {
  const predictor = createTidePredictor(
    hs.constituents.map((c) => ({ name: c.name, amplitude: c.amplitudeKn, phase: c.phaseDeg })),
  );

  // Flood/ebb peaks come straight from the extremes predictor.
  const extremes = predictor.getExtremesPrediction({ start, end });
  // ponytail: assumes mean-zero constituents (no Z0/DC-offset term) — a level-curve max
  // is a positive (flood) peak; adding a Z0 constituent would shift the baseline and could flip labels.
  const events: CurrentEvent[] = extremes.map((x) =>
    eventFromParts(x.time.toISOString(), x.high ? 'flood' : 'ebb', Math.abs(x.level)),
  );

  // Slack = sign change on a 1-minute timeline; linear-interpolate the crossing.
  const line = predictor.getTimelinePrediction({ start, end, timeFidelity: 60 });
  for (let i = 1; i < line.length; i++) {
    const a = line[i - 1], b = line[i];
    if ((a.level <= 0 && b.level > 0) || (a.level >= 0 && b.level < 0)) {
      const frac = a.level === b.level ? 0 : a.level / (a.level - b.level);
      const t = a.time.getTime() + frac * (b.time.getTime() - a.time.getTime());
      events.push(eventFromParts(new Date(t).toISOString(), 'slack', 0));
    }
  }

  events.sort((x, y) => x.utc.localeCompare(y.utc));
  return events;
}

"High tide" becomes a flood peak, "low tide" an ebb peak, and the output is the same CurrentEvent[] (slack/flood/ebb) shape the live CHS/NOAA sources emit — a drop-in third source, no restructuring downstream.

Note the ponytail: comment: classifying an extremum as flood because Neaps called it a high only works if the constituent sum is mean-zero. There's no Z0 (mean flow) term in the bundled data, so the baseline sits at zero and the labels hold. Add a mean-flow offset — say, a channel with persistent river outflow — and a weak "flood" maximum can sit entirely below zero: still ebbing, just less. The assumption is documented where it lives, because it's the first thing a future constituent refresh could silently break.

Bundling the constituents

Constituents are fetched at build time from NOAA CO-OPS mdapi harcon metadata, converted, and committed — never fetched at runtime:

// scripts/refresh-constituents.ts (excerpt)
const CM_S_PER_KNOT = 51.4444;

const constituents = rows
  .filter((c) => NEAPS_KNOWN.has(c.constituentName) && Number(c.majorAmplitude) > 0)
  .map((c) => ({
    name: c.constituentName as string,
    amplitudeKn: Number(c.majorAmplitude) / CM_S_PER_KNOT, // cm/s -> knots
    phaseDeg: Number(c.majorPhaseGMT),                     // Greenwich phase, degrees
  }));

Three gotchas live in those six lines:

Units. NOAA harcon major-axis amplitudes are cm/s; Neaps just sums whatever you hand it. Divide by 51.4444 once at generation time and every downstream level is already knots.
Phase reference. Store majorPhaseGMT (Greenwich phase, degrees). Neaps evaluates in UTC, so local-phase constants would shift every event by the timezone offset.
Silent drops. A constituent name Neaps doesn't know is silently ignored — no error, just a subtly wrong prediction. The refresh script filters against an explicit NEAPS_KNOWN set so anything unexpected is excluded deliberately at generation time, not accidentally at runtime.

NOAA's own disclaimer applies and is carried in the data file's provenance header: the data is public domain, and predictions derived from it are unofficial.

Aligning the horizon with the live path

The live path fetches per UTC day. The harmonic path must synthesize the same window, or the two series cover different spans and both fallback handoff and discrepancy comparison get skewed:

// Synthesize the whole horizon in one pass, aligned to UTC-day boundaries so the
// event window matches the live path (fetch.ts iterates UTC days from the same start).
export function synthesizeHorizon(hs: HarmonicStation, start: Date, horizonDays: number): HarmonicDayData {
  const base = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
  const end = new Date(base.getTime() + horizonDays * 86400000);
  return { events: synthesizeEvents(hs, base, end), floodDir: hs.floodDir, ebbDir: hs.ebbDir };
}

Selection: live wins, fallback declares itself

The refresh loop synthesizes harmonic data for every station with bundled constituents on every cycle — not just offline ones — then selects:

// src/select.ts
export function selectData(
  liveData: DirData | undefined,
  harmonicData: DirData | undefined,
  provider: 'chs' | 'noaa',
): Selected | undefined {
  if (liveData) return { data: liveData, source: provider, live: true };
  if (harmonicData) return { data: harmonicData, source: 'harmonic', live: false };
  return undefined;
}

Every reading that leaves the plugin carries provenance. In the /currents resource:

{
  "stationId": "PUG1701",
  "label": "Deception Pass",
  "source": "harmonic",
  "live": false,
  "unreliableForTransit": true,
  "events": [
    { "utc": "2026-07-16T14:02:00.000Z", "kind": "slack", "speedKn": 0 },
    { "utc": "2026-07-16T17:10:00.000Z", "kind": "ebb", "speedKn": 5.8 }
  ]
}

And on the environment.current delta, as SignalK meta:

meta: [{
  path: 'environment.current' as Path,
  value: {
    source: entry.source,                  // 'chs' | 'noaa' | 'harmonic'
    live: entry.live,                      // false when synthesized offline
    unreliableForTransit: station.requiresLive === true && !entry.live,
  } as unknown as object,
}],

requiresLive is a per-station config flag, pre-set on the constricted passes in the default station list. The design rule: the plugin states facts; it never suppresses a value and never editorializes. A harmonic slack estimate at Deception Pass is still useful for rough planning — deciding whether to look, not when to go. Whatever consumes the data (a chart plotter, an agent, a human reading JSON) decides what to do with unreliableForTransit: true. Silently degrading — serving a synthesized number in the same shape as an authoritative one — is how someone times a rapids transit on a model that's 25 minutes wrong.

Why harmonic predictions fall short at constricted passes

This is the part the README promises and defers, so here it is. Harmonic prediction is a linear model: the current is a sum of fixed sinusoids at astronomical frequencies,

v(t) = Σᵢ Aᵢ · cos(ωᵢ·t − φᵢ)

with amplitudes and phases fitted to a historical current-meter record. That model is excellent where the tide behaves like a superposition of long waves — open coast, wide straits. A constricted pass breaks each of its assumptions:

1. The flow is hydraulic, not wavelike. At a narrows like Seymour (which routinely exceeds 15 knots) the current is driven by the water-level difference between the basins at each end. The velocity responds roughly as the square root of that head difference, through quadratic bottom/form friction. A square root of a sum of sinusoids is not a sum of sinusoids — the response is nonlinear by construction.

2. Nonlinearity pumps energy into overtides the bundle truncates. The nonlinear terms generate shallow-water constituents — M4, M6, MS4 and friends, at multiples and sums of the astronomical frequencies — which is what makes real rapids curves asymmetric: fast-rising floods, long-tailed ebbs, double-humped peaks. The bundled stations carry 23–29 constituents each (only the ones Neaps knows); the residual distortion the fit couldn't capture doesn't vanish, it lands in the error — concentrated where the curve shape matters.

3. The error concentrates at slack — the only moment you care about. At peak flow, a 10% amplitude error changes nothing about your decision; you weren't going through Dent Rapids at max ebb anyway. Near slack, the head difference across the pass is small, so everything the constituents don't model — wind setup, atmospheric pressure gradients, river discharge in freshet, the truncated overtides — shifts the zero crossing directly. The steeper, shorter slack window at a strong narrows means a modest phase error translates to arriving with real current already running. That's the mechanism behind "off by tens of minutes," and it's why the flag is named unreliableForTransit and not something politer.

4. The fit itself is weaker. Height constituents come from decades-long water-level records at permanent gauges. Current constituents come from comparatively short current-meter deployments in turbulent, stratified water, resolved per depth bin. The inputs are noisier before the model's structural limits even apply.

None of this makes the harmonic fallback useless — Boundary Pass under harmonic synthesis is a perfectly serviceable planning baseline. It makes the fallback conditionally trustworthy, and the condition is knowable per station in advance. That's exactly what a config flag is for.

Measure the fallback while you still have ground truth

The claim above — "off by tens of minutes" — deserves numbers, per station. The trick is that the best time to measure an offline fallback is when you're online: every poll cycle where a station has both live and harmonic data, the plugin diffs them and appends a line to a local JSONL log:

// src/compare.ts — deltas are signed (harmonic − live):
// +slackDeltaMin = harmonic slack is later
export function computeDiscrepancy(
  stationId: string, label: string, live: CurrentEvent[], harmonic: CurrentEvent[], now: Date,
): Discrepancy {
  const ls = nextSlackAfter(live, now), hs = nextSlackAfter(harmonic, now);
  const lp = peakRate(live), hp = peakRate(harmonic);
  return {
    utc: now.toISOString(), stationId, label,
    slackDeltaMin: ls !== undefined && hs !== undefined ? (hs - ls) / 60000 : null,
    peakRateDeltaKn: lp !== undefined && hp !== undefined ? hp - lp : null,
  };
}

<SignalK dataDir>/signalk-currents-discrepancies.jsonl

One row per station per poll: how far off the harmonic next-slack estimate is (signed minutes) and how far off the peak rate is (signed knots). Local file only — nothing is phoned home. The write is best-effort and swallowed on failure, because diagnostics must never take down the data path they're diagnosing.

The design intent: when someone eventually asks "how wrong is the fallback at this station?", the answer is a jq one-liner over months of accumulated rows, not a shrug. The follow-up post with a season of measured deltas is the plan; this post is the mechanism.

Gotchas

NOAA harcon amplitudes are cm/s — convert to knots (÷ 51.4444) at generation time, not runtime.
Neaps silently drops constituent names it doesn't know. Filter against an explicit known set when generating the bundle, or you'll ship a prediction missing constituents with no error anywhere.
Flood/ebb labels assume mean-zero constituents. A Z0/mean-flow term would shift the baseline and can flip extremum labels.
Align synthesis windows to UTC-day boundaries to match a per-day live fetch path, or fallback handoffs jump.
You may not be able to redistribute your local constituents. NOAA is public domain; CHS is not. Check before bundling anything Canadian — the licensing boundary decides your offline coverage map, not your code.
Provenance is part of the data model, not a log line. source / live / unreliableForTransit ride on the resource payload and the SignalK meta, so every consumer sees them — not just whoever reads the server log.

Close

This plugin is part of the open-source navigation stack for an all-electric charter catamaran that will spend its life transiting exactly these passes — which is why the fallback that keeps currents flowing offline also has to be honest about where it can't be trusted. Code, bundled constituents, and the refresh script: github.com/sailingnaturali/signalk-currents.

Related: why generic weather MCPs fail for marine navigation — the same verify-against-reality instinct, with NDBC buoys as ground truth — and LLM agents confabulating data provenance, the failure mode provenance fields exist to prevent.

Running OpenClaw on a Raspberry Pi alongside SignalK

Bryan Clark — Wed, 29 Jul 2026 12:50:26 +0000

Running OpenClaw — a self-hosted, multi-channel agent gateway — on a Raspberry Pi 5 next to SignalK, so you can DM the boat over Telegram and get live vessel readings back. The traps that cost me time are up front — the gateway.mode start-block, SI-unit conversion, no history without InfluxDB, and a Chesterton's-fence with the ollama plugin — then the walkthrough, then what I found tuning the standing prompt down. Jump to the gotchas.

There's no existing writeup for this combination anywhere I could find, so here's the whole thing: what to know before you start, the setup that actually works, and the token-cost tuning that made it cheap enough to leave running.

The build

OpenClaw is a Node/TypeScript daemon you run on your own hardware; you talk to an LLM-backed agent over chat channels (Telegram, Slack, etc.). SignalK is the open marine data server that normalises NMEA 2000/0183 into one JSON model. Put them on the same Pi and you get a boat assistant you DM from your phone that can read live vessel state.

They share the box but stay in their own lanes. OpenClaw reads SignalK over HTTP — it does not run inside the marine stack:

  Raspberry Pi 5 (8 GB)
  ┌─────────────────────────────────────────────┐
  │  SignalK (Docker)          OpenClaw (native) │
  │  localhost:3000  ◀── HTTP ──  gateway daemon │
  │  + InfluxDB/Grafana           (systemd user) │
  └─────────────────────────────────────────────┘
            ▲                          ▲
       NMEA 2000/0183            Telegram DM

SignalK is typically already running in Docker on localhost:3000 next to InfluxDB and Grafana. OpenClaw installs natively alongside it. No MCP server, no plugin inside SignalK — the agent just curls the SignalK REST API.

Gotchas first

These are the ones that don't show up until you hit them.

1. The gateway won't start without `gateway.mode`

If the config is missing gateway.mode, the daemon refuses to start:

Gateway start blocked: set gateway.mode=local

Onboarding sets this for you. But if you hand-edit the config and drop the key — or a tool rewrites it — OpenClaw treats the missing key as suspicious/clobbered config and blocks the start rather than guessing. The fix is one command:

openclaw config set gateway.mode local

(Or re-run onboarding with openclaw onboard --mode local.) See the gateway troubleshooting docs.

2. SignalK values are SI — the agent must convert

SignalK stores everything in SI units. A raw read looks fine and is silently wrong for a human:

speed      → m/s     (× 1.94384 for knots)
angles     → radians (× 57.2958 for degrees)
temperature→ Kelvin  (− 273.15 for °C)
depth      → metres

So environment.wind.speedApparent comes back as 8.5 — that's 8.5 m/s, i.e. ~16.5 knots, not 8.5 knots. If you don't tell the agent to convert, it will happily report the SI number as if it were the human unit. Bake the conversions into the agent's instructions (or a skill), and spell out the target units.

3. No history without InfluxDB

SignalK's REST API serves live values fine anonymously. But the history endpoint returns a 404 unless the InfluxDB-backed history plugin is running:

$ curl -s http://localhost:3000/signalk/v2/history/values?paths=electrical.batteries.house.stateOfCharge
# 404 unless signalk-to-influxdb (+ history API) is installed and running

Without it the agent is live-only — it answers "what's the depth now," not "what was the minimum overnight." If you want the agent to reason over trends, stand up the history plugin first; otherwise scope its instructions to present-tense questions.

4. `jq` isn't installed by default

Raspberry Pi OS ships without jq. If your agent instructions pipe curl through jq, they'll fail on a fresh box:

$ curl -s http://localhost:3000/signalk/v1/api/vessels/self/environment/depth/belowTransducer | jq .value
bash: jq: command not found

Two options: sudo apt install jq, or just don't — hand the agent the raw JSON and let it parse. An LLM reads { "value": 4.2, "timestamp": "…" } without help. I went with raw JSON; one fewer moving part on the boat.

5. Chesterton's fence — the `ollama` plugin does more than you think

I disabled the ollama plugin assuming it was only a (dead, for me) web-search provider. Later a local Ollama model failed to load:

No API provider registered for api: ollama

The ollama plugin also registers the Ollama API runtime — the thing that lets you use Ollama as a model backend, not just a search tool. Disabling it pulled the backend out from under the model. The lesson is the old one: don't disable a plugin until you know everything it provides. (Re-enabling it fixed the load.)

The walkthrough

Install (native)

OpenClaw supports Docker, but on a Pi that's already running SignalK's own Docker stack I installed OpenClaw natively and let it manage its own daemon — it keeps the marine containers isolated and the agent's lifecycle separate. The installer targets Node 24 by default (the supported range is Node 22.22.3+, 24.15+, or 25.9+) and handles the runtime for you:

curl -fsSL https://openclaw.ai/install.sh | bash
# or: npm install -g openclaw@latest

Then the guided setup — it walks you through auth (an Anthropic API key, or an OAuth login), model choice, and the daemon:

openclaw onboard
openclaw onboard --install-daemon   # installs a systemd user service

On a headless Pi, the user service dies at logout unless you enable lingering:

sudo loginctl enable-linger "$USER"

That's the piece that makes it survive a reboot. See the install docs.

Make a bot with @BotFather, then point OpenClaw at the token — either in config or via env:

openclaw config set channels.telegram.botToken "<BOT_TOKEN>"
# or export TELEGRAM_BOT_TOKEN=<BOT_TOKEN>

Keep DMs gated with pairing so a stranger who finds the bot can't drive your boat:

// channels.telegram
{ "dmPolicy": "pairing" }

DM the bot, then approve the code it gives you (codes expire after an hour):

openclaw pairing approve telegram <CODE>

Details in the Telegram channel docs.

Reading SignalK over HTTP — no MCP needed

SignalK's REST API is anonymous when allow_readonly is on, so you don't need a custom SignalK MCP server for reads. Give the agent the exec tool and let it curl. A SignalK dotted path maps straight to URL slashes:

# environment.depth.belowTransducer  →  .../environment/depth/belowTransducer
curl -s http://localhost:3000/signalk/v1/api/vessels/self/environment/depth/belowTransducer

{ "value": 4.2, "timestamp": "2026-07-27T00:00:00Z", "meta": { "units": "m" } }

Grab a whole subtree in one call:

curl -s http://localhost:3000/signalk/v1/api/vessels/self/electrical

The one prerequisite: exec only exists in certain tool profiles — which is the first tuning finding below.

Tuning finding 1 — skill vs the agent file

OpenClaw injects workspace files into context every turn: a SOUL.md persona and an AGENTS.md instruction/memory file. Skills live at workspace/skills/<name>/SKILL.md — the skill's name+description is advertised every turn, but its body loads on demand when the skill fires.

So where do the SignalK-reading instructions belong — always-on in AGENTS.md, or in a SKILL.md? Intuition says the skill: pay for the body only when you use it. I measured prompt tokens per turn both ways:

Turn	in AGENTS.md (always-on)	as a skill (on-demand)	Δ
No-tool question	13,808	13,380	−428 (skill wins)
Single boat read	14,070	14,427	+357 (skill loses)
Multi boat read	16,134	16,628	+494 (skill loses)

Counterintuitive but consistent: for an agent whose whole job is this domain, the always-on agent file is slightly cheaper. The skill's description still sits in context every turn (alongside every other skill's), and loading its body on a domain turn costs more than the tiny always-on snippet it replaced. The skill only wins when most turns don't touch the domain — and for a boat agent, most turns do.

(This is the same always-on-vs-conditional split we hit on a different framework — see the related post below.)

Tuning finding 2 — cutting the ~14k standing prompt

Every turn, even a no-tool question, carries a ~14k-token standing prompt: base preamble + tool schemas + workspace files. That's structural to a general-purpose gateway. Three things I tried to shrink it, in order of what actually worked.

What worked — the tool profile

OpenClaw gates tools by tools.profile: minimal (just session_status), coding (filesystem + runtime/exec + web + more), messaging, and full. Only coding grants both exec and filesystem — which is why the SignalK-over-curl approach needs it.

But coding also drags in a pile of dev-tool schemas a boat agent never calls. If all you need is shell + file read/write, drop to minimal and additively re-allow just those two groups:

// tools
{
  "profile": "minimal",
  "alsoAllow": ["group:runtime", "group:fs"]
}

group:runtime is exec/process; group:fs is read/write/edit. That cut ~5,000 tokens/turn (~25%) — pure schema for tools the agent never uses — with zero functional loss. See the tool-profile docs.

What did NOT work — disabling plugins

I assumed the loaded plugins (browser, canvas, phone-control, talk-voice…) were bloating the prompt. Disabling four of them saved ~270 tokens — nothing.

Why: tool schemas are gated by tool policy, not plugin state. Once the minimal profile excludes a tool, its schema is already gone whether or not the plugin loads. So:

Disabling a plugin does not save prompt tokens if the profile already denies its tools.

(Still disable unused plugins — for the Pi's RAM, CPU, and boot time. Just don't expect a token win.)

The real lever — caching, not token count

The standing prompt bills at full price only on a cold turn. OpenClaw auto-injects Anthropic cache_control on the stable prefix, so the ~14k reads from cache at ~10% on warm turns. I watched it in one session: the cold turn wrote ~14k tokens to cache; the next same-session turn read ~14k from cache and wrote only ~150.

For bursty use — messages minutes apart, which is exactly how you DM a boat — the default 5-minute cache TTL keeps cold-starting. Bump it:

// long cache retention → 1h TTL
{ "cacheRetention": "long" }

One version caveat: OpenClaw is careful to order the stable context files ahead of the churny heartbeat file so heartbeat updates don't bust the cached prefix — but older builds had a cache-busting bug where a per-message value landed inside the cached block and re-wrote the whole prefix every turn. If your "cached" reads look like full-price writes, check your version. See the prompt-caching docs.

Bonus — a watch that stays quiet

Once the agent can read SignalK, a natural next step is a scheduled check that only speaks when something's wrong. OpenClaw's cron supports a deterministic --trigger-script gate: the script inspects SignalK (any non-normal notification, or a battery/depth/tank threshold), returns { fire, message?, state? }, and the agent only composes a Telegram heads-up when fire is true — de-duped on state so it alerts on change, not every tick. A watch that's silent when all's well. That's its own post; the cron docs have the shape.

Close

This came out of building an AI ops layer for an all-electric charter catamaran, where "what's our depth?" should be a Telegram DM away and the standing prompt cheap enough to leave running on a Pi. If you're standing this up yourself, the two references worth bookmarking are the OpenClaw docs and signalk.org — the rest is the six lines of gotchas above.

Related: Why your agent ignores its skill body but obeys the system prompt — the always-on-vs-conditional split behind tuning finding 1; and Why we kept named MCP tools despite a 96% token saving — the tokens-vs-reliability tradeoff for boat agents.

DEV Community: Bryan Clark

Two alert lanes: the siren shouldn't depend on an LLM

Problem: the alarm path became a cron job

Diagnosis: count the things that have to work

What I tried, and why each one failed

1. A path allowlist to decide what pages

2. A coalesce window re-armed on every arriving row

3. Posting {"message": "..."} to the agent hook

The fix

Why it matters, and the gotchas nearby

Close

SignalK's two token classes: why plugin routes 401 your device token

Problem

Diagnosis: two token classes

What we tried (and why it failed)

The fix

Why it matters / gotchas

If you're the one writing the plugin

Close

How I proved a from-scratch harmonic tide engine is accurate

The trap that makes a correct engine look wrong

Method: golden vectors against an oracle

The receipt: vs NOAA's own predictions

The honest residual — why ~8 minutes

A note on data sourcing

Close

Tide predictions read higher than the tables? Suspect the datum

Problem

Diagnosis

What we tried (and why it failed)

The fix

The bonus find: a station no datum can explain

Why it matters / gotchas

Close

Shipping Canadian CHS station data without redistributing the licensed file

Problem

Diagnosis: copyright vs. contract

The tell: the opaque station id

What we tried (and why it crossed the line)

The fix: a pipeline, not a download

1. The registry ships facts and zero provider ids

2. Resolve the opaque handle at runtime, under your own licence

Why it matters / gotchas

Close

Porting a tide engine to Swift with the original as the test oracle

The problem: numeric ports fail silently

Wire the original up as an oracle

Port layer by layer, gate each layer

Don't port the catalog — generate it

Golden checks → swift test → CI

Matching the reference isn't the finish line

Trim the API before anyone depends on it

Three transferable lessons

Bench your own workload before you switch LLM vendors

The temptation

The decision rule

The harness

What the bench surfaced before it produced a number

The numbers

The fairness caveat, again

Why it matters

The NMEA 2000 paradox has an open-source answer

Identical beeps: severity is data, not a sound

You are not the monitoring system

Plain language under stress

Lock-in: integrate, don't replace

The gap they're right about

Where this lands

MCP server or a curl recipe in AGENTS.md? Measure the breakeven

Two ways to let an agent read a boat

Round 1 — standing cost, the part everyone measures

Round 2 — the part the benchmarks skip

The breakeven formula

Prompt caching moves k*, and I measured by how much

The half that tokens don't measure

What the prose recipe is really asking for

Caveats, before you quote my numbers

Where it lands

A persistent-queue HTTP reporter for distress traffic over flaky internet

Why this matters for safety at sea

3. Posting `{"message": "..."}` to the agent hook

Golden checks → `swift test` → CI

1. The gateway won't start without `gateway.mode`

4. `jq` isn't installed by default

5. Chesterton's fence — the `ollama` plugin does more than you think