node-red-contrib-ntrip 0.2.3 → 0.2.8

package/doc/architecture/adr/0002-ntrip-uploader-extension.md

@@ -0,0 +1,71 @@
+# ADR-0002: NTRIP uploader as full-replacement extension of the upstream client
+
+## Status
+
+Accepted in 0.2.0.
+
+## Context
+
+The upstream `ntrip-client` npm package implements the *download* side of
+NTRIP only — it connects to a caster and emits received bytes. We needed the
+*upload* side too: open a socket, send a SOURCE / POST handshake, then forward
+locally-produced bytes to the caster (e.g. RTCM from an RTKBase station).
+
+Four authentication-mode handshakes are commonly seen in the wild:
+
+- `legacy` — `SOURCE <mp>` over plain TCP, rtk2go accepts this.
+- `hybrid` — `SOURCE <mp>` plus a Basic Auth header. SNIP accepts this.
+- `ntripv1` — `POST` over HTTP/1.0.
+- `ntripv2` — `POST` over HTTP/1.1 with `Ntrip-Version: Ntrip/2.0`.
+
+The upstream client's `_connect()` method handles only the download handshake.
+Three options to add upload:
+
+1. **Fork the upstream package.** Maintain a copy in this repo. Heavy
+   maintenance burden.
+2. **Submit a PR upstream.** Slow turn-around; upstream may not accept the
+   shape we need.
+3. **Subclass the upstream client locally** and override the connection method
+   to write a different handshake. Light footprint.
+
+## Decision
+
+Subclass locally. [ntrip/lib/ntrip-client.js](../../../ntrip/lib/ntrip-client.js)
+defines `NtripClientUploader extends NtripClient` and overrides `_connect()`
+to emit the right handshake string per `authmode`.
+
+The constructor also validates CR/LF in `mountpoint`/`username`/`password` to
+prevent header injection — the rejection happens at instance construction so
+malicious config never reaches the wire.
+
+## Consequences
+
+**Positive**
+
+- No fork to maintain. Upstream upgrades flow through (`npm update`).
+- All upload-specific logic is in one file, easy to audit.
+- The CR/LF guard is co-located with the only code that interpolates those
+  fields, minimising the chance of a future caller bypassing it.
+
+**Negative**
+
+- `_connect()` is a *full replacement*, not a delegation. Any improvement
+  upstream makes to the connection lifecycle (timeout handling, IPv6, keep-
+  alive, TLS upgrade) will not propagate into our uploader path.
+- The subclass depends on internal-ish state of the parent (`this.client`,
+  `this.timeout`, `_onError`, `_onData`). A breaking refactor upstream would
+  surface as a runtime error in this package.
+- The fork-by-extension makes a future TLS migration harder than it would be
+  in a from-scratch implementation.
+
+**Trade-offs**
+
+- Picking this over a full fork chose *easy upstream upgrades* over *insulation
+  from upstream API churn*. The upstream package has been stable for years, so
+  the bet has paid off so far.
+
+## Related
+
+- Code: [ntrip/lib/ntrip-client.js:1-100](../../../ntrip/lib/ntrip-client.js#L1-L100)
+- Referenced in: [Refactoring Recommendations §3](../refactoring-recommendations.md)
+- Related ADRs: [ADR-0004](0004-stateful-handshake-interception.md) (handshake state machine sits on top of this subclass)

package/doc/architecture/adr/0003-two-output-decoder-design.md

@@ -0,0 +1,73 @@
+# ADR-0003: Two-output `[ok, error]` convention for decoders / encoder
+
+## Status
+
+Accepted in the original design, **reaffirmed in 0.2.6** after a brief
+deviation in 0.2.5 that added `node.error()` calls inside the catch blocks.
+
+## Context
+
+Each of `RtcmDecoder`, `NmeaDecoder`, `NmeaEncoder` can fail per message —
+unexpected payload type, malformed bytes, unknown sentence/message ID. There
+are two idiomatic Node-RED patterns to report such failures:
+
+- **`node.error(err, msg)`** — logs to the Node-RED `[error]` log and, with the
+  `msg` second argument, hands the message off to any wired Catch node.
+- **A second output port** — `node.send([okMsg, errMsg])`. Flows wire the
+  second port to a debug node, MQTT publish, in-memory queue, etc.
+
+Both are legitimate. The choice matters when the decoder is fed high-rate
+mismatched binary — for example, the README's own demo flow wires an
+`NmeaDecoder` onto an `NtripClient` download output as an illustration of
+"the stream can be split", even though RTK2Go only emits RTCM. Every byte that
+arrives produces a NMEA decode failure.
+
+In 0.2.5 the catch blocks called both `node.send` *and* `node.error`. Users
+running the demo immediately saw a flood of:
+
+```
+12 May 19:20:21 - [error] [NmeaDecoder:fa8…] Error: NMEA decode exception: Invalid delimiter (expected $ or !, got �)
+```
+
+— one per chunk, several per second. The log became unusable.
+
+## Decision
+
+Per-message decode failures are reported on the **second output only**, never
+via `node.error`. `node.error` is reserved for unhandled-state conditions
+(node construction failure, unsupported configuration) where the node can no
+longer make forward progress.
+
+If a downstream flow wants centralised error handling, it should wire the
+second output to its own Catch-equivalent — typically a Function node that
+logs and forwards.
+
+## Consequences
+
+**Positive**
+
+- Decoders fed mismatched binary stop polluting the Node-RED error log.
+- The error output port is opt-in: ignore it and errors are silently dropped
+  (the decoder still bumps `invalidMessagesReceived` and updates the status
+  badge, so the user can tell from the editor that something is wrong).
+- Behaviour is consistent across all three transformer nodes.
+
+**Negative**
+
+- Users coming from packages that use `node.error` for everything need to wire
+  the second output explicitly — a small learning-curve cost.
+- The Catch-node integration that `node.error` provides is lost. A workaround
+  is to chain a Function node that calls `node.error()` if the user wants
+  Catch firing.
+
+**Trade-offs**
+
+- This favours **operability over discoverability** — a quiet error log is
+  more important than out-of-the-box Catch integration, given the documented
+  demo wiring.
+
+## Related
+
+- Code: [ntrip/nodes/nmea-decoder-node.js:33-42](../../../ntrip/nodes/nmea-decoder-node.js#L33-L42), [ntrip/nodes/rtcm-decoder-node.js:35-55](../../../ntrip/nodes/rtcm-decoder-node.js#L35-L55), [ntrip/nodes/nmea-encoder-node.js:155-166](../../../ntrip/nodes/nmea-encoder-node.js#L155-L166)
+- Regression spec: [test/nmea-decoder.spec.js](../../../test/nmea-decoder.spec.js) `does not call node.error on decode failure (regression: log flood)`
+- CHANGELOG: 0.2.6 "Fixed regressions introduced in 0.2.5"

package/doc/architecture/adr/0004-stateful-handshake-interception.md

@@ -0,0 +1,74 @@
+# ADR-0004: Stateful handshake interception in the NtripClient
+
+## Status
+
+Accepted in 0.2.5.
+
+## Context
+
+The NTRIP caster replies to a successful connection with one of:
+
+- `ICY 200 OK\r\n\r\n` followed immediately by the correction stream.
+- `ICY 406 ...\r\n\r\n` (rejected — bad credentials, etc.).
+- `SOURCETABLE 200 OK\r\n\r\n` followed by the source table (returned when the
+  client did not specify a mountpoint, or specified an invalid one).
+
+These first-byte replies need to drive the node's status badge: green
+"connected", red "rejected", red "no mountpoint". After the handshake is
+processed, all subsequent bytes are application data (RTCM in download mode,
+mountpoint advertisements in upload reverse channel).
+
+Up to 0.2.4 the `'data'` listener ran `data.toString().startsWith('ICY 200 OK')`
+on every incoming chunk. This was wrong for two reasons:
+
+1. **The check inflated the message counter.** Each control reply bumped
+   `messagesReceived`, polluting the status badge.
+2. **It could drop RTCM bytes.** TCP is byte-stream — when the caster sent
+   `"ICY 200 OK\r\n\r\n" + firstRtcmFrame` in one segment, the prefix match
+   succeeded and the whole chunk (including the RTCM tail) was discarded
+   instead of forwarded.
+
+## Decision
+
+Maintain a `connected: boolean` flag on the node instance. The `'data'`
+listener checks the flag:
+
+- **`!connected`** — look at the first ~64 bytes of the chunk for an `ICY`
+  or `SOURCETABLE` prefix. If found, update status accordingly and consume the
+  handshake. If `ICY 200 OK` was found, also split at `\r\n\r\n` and forward
+  the trailing bytes as the first real data frame. Either way, set
+  `connected = true` (or, for rejection paths, leave `connected = false` and
+  log the error).
+- **`connected`** — every byte is application data; just forward it and bump
+  the counter.
+
+The flag is reset to `false` on the `'close'` event so the next reconnect
+re-enters the handshake state.
+
+## Consequences
+
+**Positive**
+
+- No byte loss at the handshake boundary.
+- Counter reflects application data only.
+- Behaviour after reconnect matches behaviour on first connect — no special
+  case for reconnects.
+
+**Negative**
+
+- Two paths in the data listener that future maintainers must keep aligned.
+- A spec for the trailing-bytes split would need a fake caster — currently
+  covered by manual testing only. See
+  [Future Improvements](../future-improvements.md).
+
+**Trade-offs**
+
+- Choosing a state-machine over a "stateless prefix check every time" approach
+  trades minimal code complexity (one extra boolean) for correct behaviour on
+  the boundary case.
+
+## Related
+
+- Code: [ntrip/nodes/ntrip-client-node.js:75-115](../../../ntrip/nodes/ntrip-client-node.js#L75-L115)
+- CHANGELOG: 0.2.5 "Fixed NTRIP client node — Handshake detection is now stateful"
+- Related ADRs: [ADR-0002](0002-ntrip-uploader-extension.md) (the underlying client this layer sits on)

package/doc/architecture/adr/0005-rtcm-partial-frame-buffer.md

@@ -0,0 +1,87 @@
+# ADR-0005: Carry-over buffer for partial RTCM frames
+
+## Status
+
+Accepted in 0.2.5.
+
+## Context
+
+RTCM 3 frames are variable-length and routinely cross TCP packet boundaries.
+A typical RTCM 1077 (MSM7 GPS) frame is ~200 bytes; an MTU is ~1460 bytes
+payload — perfectly possible for a frame to span two TCP segments, and very
+common when many frames are sent back-to-back.
+
+The upstream `@gnss/rtcm` library's `RtcmTransport.decode(buffer)`:
+
+- Returns `[message, length]` if `buffer` starts with a complete frame.
+- Throws if the buffer starts with what looks like an RTCM frame but ends
+  before the frame does.
+
+Up to 0.2.4 the decoder consumed one chunk at a time without any
+buffer-carry-over: every throw inside the chunk caused the loop to break and
+any trailing bytes were discarded. With ~5 frames per packet boundary and
+~100 frames/s, this lost ~5 % of frames on a busy stream.
+
+## Decision
+
+Carry partial-frame bytes across input events:
+
+```javascript
+node.pendingBuffer = Buffer.alloc(0);
+
+on('input', msg) {
+    let buffer = pendingBuffer.length > 0
+        ? Buffer.concat([pendingBuffer, msg.payload])
+        : msg.payload;
+
+    while (buffer.length > 0) {
+        try {
+            [message, length] = RtcmTransport.decode(buffer);
+        } catch (ex) {
+            // Likely partial frame — keep buffer for next chunk.
+            if (buffer.length > 64KB) {
+                // Garbage cap — emit error and clear.
+                emit_error(); buffer = empty;
+            }
+            break;
+        }
+        if (length <= 0 || length > buffer.length) break;   // forward-progress guard
+        emit_decoded(); buffer = buffer.slice(length);
+    }
+    pendingBuffer = buffer;
+}
+```
+
+The 64 KB cap stops the buffer growing unboundedly when the upstream feeds
+non-RTCM bytes. The forward-progress guard stops a hypothetical infinite loop
+on a zero-length decode.
+
+## Consequences
+
+**Positive**
+
+- Frames that straddle TCP boundaries are decoded correctly — no frame loss
+  in normal operation.
+- The cap means a misconfigured flow (e.g. RTCM decoder fed NMEA) eventually
+  produces an error rather than running out of memory.
+- The forward-progress guard makes the loop terminate under any decoder
+  behaviour.
+
+**Negative**
+
+- The node now holds a per-instance buffer up to 64 KB. For 100 instances in
+  one flow that's 6.4 MB worst-case — not significant, but worth noting.
+- Decode latency at the chunk boundary is slightly higher: the decoder has to
+  retry as more bytes arrive. In practice this is one extra round of
+  `decode()` per chunk.
+
+**Trade-offs**
+
+- Chose **correctness on stream boundaries** over **per-call statelessness**.
+  A stateless decoder would be easier to reason about, but would lose frames.
+
+## Related
+
+- Code: [ntrip/nodes/rtcm-decoder-node.js:14-78](../../../ntrip/nodes/rtcm-decoder-node.js#L14-L78)
+- Regression spec: [test/rtcm-decoder.spec.js](../../../test/rtcm-decoder.spec.js) `reassembles a frame split across two input events (carry-over buffer)`
+- CHANGELOG: 0.2.5 "Fixed RTCM decoder node — Frames that straddle TCP packet boundaries are now buffered"

package/doc/architecture/adr/0006-nmea-multi-sentence-split.md

@@ -0,0 +1,66 @@
+# ADR-0006: Multi-sentence splitting in the NMEA decoder
+
+## Status
+
+Accepted in 0.2.5.
+
+## Context
+
+A serial GNSS receiver typically emits several NMEA sentences as a batch each
+cycle (e.g. `$GPGGA…\r\n$GPRMC…\r\n$GPGSA…\r\n$GPGSV…\r\n`). Likewise, a TCP
+producer of NMEA data may pack multiple sentences into one segment.
+
+Pre-0.2.5 the decoder called `NmeaTransport.decode(buffer)` exactly once on
+whatever it received. If the input contained more than one sentence, only the
+first decoded successfully — the trailing sentences were either lost
+(`NmeaTransport` silently took the prefix) or caused the whole call to throw
+(if the parser was strict). The README claimed the decoder accepted "either a
+single or multiple NMEA messages" — that was untrue.
+
+Two approaches to fix:
+
+1. **Buffer-and-split.** Treat the input as a string, split on `\r\n` (or
+   `\n`), trim each piece, decode each non-empty piece.
+2. **Push-down to the library.** Ask `@gnss/nmea` to handle multi-sentence
+   input. Out of scope — would require upstream changes.
+
+## Decision
+
+Split-and-decode locally. The decoder splits on `/\r?\n/`, trims each chunk,
+skips empty ones, and decodes each remaining sentence individually. Each
+successful decode produces its own output message — so a batch of four
+sentences emits four output messages, not one.
+
+Errors are reported per-sentence. The error output uses the original
+`msg.payload` (or `msg.payload.nmeaMessage`) as `input` so a downstream
+debugger sees the raw bytes that arrived, not the per-sentence string that
+failed (see [Behavioural Design](../behavioural-design.md)).
+
+## Consequences
+
+**Positive**
+
+- Matches the documented behaviour ("accepts single or multiple sentences").
+- Downstream wiring is uniform: one decoded sentence = one output message,
+  regardless of how the producer chose to chunk.
+- Naturally handles trailing/leading whitespace and stray empty lines.
+
+**Negative**
+
+- A chunk that contains both valid and invalid sentences fans out a mix of ok
+  and error messages — downstream nodes that assumed "one input ⇒ one output"
+  need adjustment.
+- Per-sentence trimming adds a small amount of work compared to a single
+  parser invocation. For typical NMEA volumes this is negligible.
+
+**Trade-offs**
+
+- Picked **per-sentence semantics** (one in, N out) over **chunk semantics**
+  (one in, one out) because the value of getting structured per-sentence
+  output far outweighs the slight asymmetry.
+
+## Related
+
+- Code: [ntrip/nodes/nmea-decoder-node.js:50-89](../../../ntrip/nodes/nmea-decoder-node.js#L50-L89)
+- Regression spec: [test/nmea-decoder.spec.js](../../../test/nmea-decoder.spec.js) `splits a multi-sentence chunk into separate output messages`
+- CHANGELOG: 0.2.5 "Fixed NMEA decoder node — A single chunk containing multiple `\r\n`-delimited NMEA sentences is now decoded sentence by sentence"

package/doc/architecture/adr/0007-mocha-test-helper-stack.md

@@ -0,0 +1,67 @@
+# ADR-0007: Mocha + node-red-node-test-helper for the test suite
+
+## Status
+
+Accepted in 0.2.6.
+
+## Context
+
+Up to 0.2.5 the package had no automated tests — three patch releases in two
+weeks shipped regressions that an even minimal suite would have caught.
+Adding tests was overdue. Choices:
+
+- **Mocha** vs **Jest** as the runner. Mocha is the dominant choice for
+  published `node-red-contrib-*` packages; Jest's auto-mocking and snapshotting
+  add nothing this package needs.
+- **`node-red-node-test-helper`** vs **direct invocation of node factories
+  with a hand-rolled `RED` stub**. The helper spins up a real Node-RED runtime
+  in-process, loads a flow, and exposes wired nodes. A hand-rolled stub would
+  let tests run faster but would not exercise the real lifecycle hooks
+  (`registerType`, `createNode`, `node.receive`, `node.send`) — which is
+  exactly where the recent regressions lived.
+- **`chai` v4 vs v5.** v5 is ESM-only. The package is CommonJS and there is
+  no reason to move it; pin v4.
+
+## Decision
+
+- Mocha for the test runner.
+- `node-red-node-test-helper` for the in-process Node-RED runtime.
+- `chai` v4 for the assertion DSL.
+- `node-red` itself as a dev dep (required by the helper from v0.3 onwards).
+
+Tests live under `test/` with one `*.spec.js` per node. Each previously-fixed
+regression has a dedicated test tagged `(regression: …)` so they can be run
+in isolation with `mocha -g regression`.
+
+CI runs `npm test` across the existing matrix (Node 18 / 20 / 22).
+
+## Consequences
+
+**Positive**
+
+- Real Node-RED runtime — tests verify the actual `registerType` + `createNode`
+  + `node.send` path, not a stub.
+- Each spec file is small (~100 LOC) and self-contained.
+- Regression tests are explicit — visible in test names, locked in for the
+  long term.
+- CI gate prevents accidental regressions on every push.
+
+**Negative**
+
+- `node-red` is a ~400-package dev dependency tree, with some known
+  vulnerabilities (all dev-only, not reachable in the published artefact).
+- First test run is slower (~80 ms helper startup) than a unit test on plain
+  functions would be.
+- Spec authors have to learn the `helper.load(...)` + `helper.getNode(...)`
+  +`on('input', …)` pattern — slight learning curve.
+
+**Trade-offs**
+
+- Chose **realism** over **speed and small dep tree**. For four nodes with
+  tight Node-RED integration, integrating the real runtime is worth the
+  weight.
+
+## Related
+
+- Code: [test/](../../../test/) and [.github/workflows/node.js.yml](../../../.github/workflows/node.js.yml)
+- Statistics: [statistics.md](../statistics.md) "Test suite" section

package/doc/architecture/adr/0008-coordinate-gating-sentinel.md

@@ -0,0 +1,76 @@
+# ADR-0008: `(0, 0, 0)` as the "no location" sentinel for GGA emission
+
+## Status
+
+Accepted in 0.2.5.
+
+## Context
+
+Many NTRIP casters require a position fix from the client before they will
+stream corrections — they need to know which network-RTK base station to
+deliver corrections from. The standard way to convey the fix is a periodic
+NMEA `GGA` sentence from the client to the caster. The upstream `ntrip-client`
+package's `xyz` option turns on this behaviour: if `xyz` is set, a `GGA` is
+synthesised from those coordinates and sent every `interval` ms.
+
+In the editor form the user supplies three numeric fields (X / Y / Z) plus an
+interval. There needs to be a way to say "I have no location, do not send
+GGA" — for casters that *don't* require GGA, sending a synthetic one is
+unnecessary noise.
+
+Two options:
+
+1. **A dedicated checkbox / radio** (`Send periodic GGA: yes/no`).
+2. **A sentinel value** — treat `(0, 0, 0)` as "no location".
+
+Pre-0.2.5 the code used `x && y && z` as the gate, which had the wrong
+semantics — *any* zero component (e.g. someone on the equator with X≈6378km,
+Y=0, Z=0) disabled the GGA.
+
+## Decision
+
+Use `(0, 0, 0)` as the sentinel. The check is:
+
+```javascript
+if (Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)
+    && !(x === 0 && y === 0 && z === 0)) {
+    options.xyz = [x, y, z];
+}
+```
+
+- All three must be finite — `NaN` (the result of `parseFloat('')` on an
+  empty form) does not enable GGA.
+- The all-zero triple is the only excluded value.
+- Coordinates with one or two zero components are fine — they fall through to
+  the caster.
+
+## Consequences
+
+**Positive**
+
+- One-field-fewer in the editor form.
+- Equator / axis-aligned positions work correctly.
+- Matches the convention used by other NTRIP tooling (rtklib, str2str): if
+  you don't want GGA, you set the coordinates to all zeros.
+
+**Negative**
+
+- Discoverability — a user looking at the form has no in-UI hint that
+  `(0, 0, 0)` is special. The README and the editor help text document this,
+  but a fresh user might not read either.
+- The Earth's center of mass at `(0, 0, 0)` ECEF is technically a *real*
+  position. Not a meaningful place for a GNSS receiver to be, but the sentinel
+  collides with one mathematically valid input.
+
+**Trade-offs**
+
+- Picked **minimum form surface** over **explicit toggle**. If user feedback
+  reports confusion, swap to an explicit checkbox in a future minor release
+  and keep the sentinel for backward compatibility.
+
+## Related
+
+- Code: [ntrip/nodes/ntrip-client-node.js:43-46](../../../ntrip/nodes/ntrip-client-node.js#L43-L46)
+- Editor help text: [ntrip/99-ntrip.html](../../../ntrip/99-ntrip.html) "Optional ECEF coordinate triple" block
+- README: "Notes on usage — NTRIP Client: coordinates"
+- CHANGELOG: 0.2.5 "Coordinate guard changed from `x && y && z` to `not all zero`"

package/doc/architecture/adr/README.md

@@ -0,0 +1,18 @@
+# ADR Index
+
+This folder contains Architecture Decision Records. One file per ADR, numbered
+in the order they were accepted.
+
+| # | Title | Status | Date accepted |
+|---|-------|--------|---------------|
+| [0001](0001-single-registration-file.md) | Single registration file for all nodes | Accepted | original design |
+| [0002](0002-ntrip-uploader-extension.md) | NTRIP uploader as full-replacement extension of the upstream client | Accepted | 0.2.0 |
+| [0003](0003-two-output-decoder-design.md) | Two-output `[ok, error]` convention for decoders / encoder | Accepted | original design (reaffirmed in 0.2.6) |
+| [0004](0004-stateful-handshake-interception.md) | Stateful handshake interception in the NtripClient | Accepted | 0.2.5 |
+| [0005](0005-rtcm-partial-frame-buffer.md) | Carry-over buffer for partial RTCM frames | Accepted | 0.2.5 |
+| [0006](0006-nmea-multi-sentence-split.md) | Multi-sentence splitting in the NMEA decoder | Accepted | 0.2.5 |
+| [0007](0007-mocha-test-helper-stack.md) | Mocha + node-red-node-test-helper for the test suite | Accepted | 0.2.6 |
+| [0008](0008-coordinate-gating-sentinel.md) | `(0, 0, 0)` as the "no location" sentinel for GGA emission | Accepted | 0.2.5 |
+
+See [../architecture-decisions.md](../architecture-decisions.md) for the
+template and the criteria for when to add a new ADR.

package/doc/architecture/architecture-decisions.md

@@ -0,0 +1,60 @@
+# Architecture Decisions
+
+This chapter is the index of Architecture Decision Records (ADRs). Each
+individual ADR is stored as its own markdown file under [adr/](adr/) and
+follows a compact template (Status / Context / Decision / Consequences /
+Related).
+
+## Index
+
+| # | Title | Status |
+|---|-------|--------|
+| [0001](adr/0001-single-registration-file.md) | Single registration file for all nodes | Accepted |
+| [0002](adr/0002-ntrip-uploader-extension.md) | NTRIP uploader as full-replacement extension of the upstream client | Accepted |
+| [0003](adr/0003-two-output-decoder-design.md) | Two-output `[ok, error]` convention for decoders / encoder | Accepted |
+| [0004](adr/0004-stateful-handshake-interception.md) | Stateful handshake interception in the NtripClient | Accepted |
+| [0005](adr/0005-rtcm-partial-frame-buffer.md) | Carry-over buffer for partial RTCM frames | Accepted |
+| [0006](adr/0006-nmea-multi-sentence-split.md) | Multi-sentence splitting in the NMEA decoder | Accepted |
+| [0007](adr/0007-mocha-test-helper-stack.md) | Mocha + node-red-node-test-helper for the test suite | Accepted |
+| [0008](adr/0008-coordinate-gating-sentinel.md) | `(0, 0, 0)` as the "no location" sentinel for GGA emission | Accepted |
+
+## When to add a new ADR
+
+Add one when a decision is non-obvious and would surprise a contributor reading
+the code six months from now. Typical signals:
+
+- The code does something differently from how upstream / community examples
+  do it.
+- The choice was load-bearing — reverting it would break a documented contract.
+- There is a clear trade-off (e.g. simpler code vs. larger memory footprint)
+  that future maintainers should understand before changing direction.
+
+## When *not* to add an ADR
+
+Skip the formality for routine bug fixes, refactors that don't change external
+behaviour, or decisions that are already obvious from idiomatic style. The
+goal is a small, stable archive — not a write-up of every commit.
+
+## Template
+
+```markdown
+# ADR-NNNN: Short imperative title
+
+## Status
+Proposed | Accepted | Superseded by ADR-MMMM | Deprecated
+
+## Context
+What problem are we solving? What constraints / forces are at play?
+
+## Decision
+What we are going to do, in one or two sentences.
+
+## Consequences
+- Positive: …
+- Negative: …
+- Trade-offs: …
+
+## Related
+- Code: [path/to/file.js:LL-LL](../../path/to/file.js#LLL-LLL)
+- ADRs: [[ADR-XXXX](XXXX-title.md)]
+```