signalk-underkeel 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/CHANGELOG.md +796 -0
  2. package/LICENSE +190 -0
  3. package/README.md +514 -2
  4. package/docs/images/how-it-works/combo-pic.jpg +0 -0
  5. package/docs/images/how-it-works/config.png +0 -0
  6. package/docs/images/how-it-works/freeboard-open-setup.jpg +0 -0
  7. package/docs/images/how-it-works/freeboard-panel.jpg +0 -0
  8. package/docs/images/how-it-works/freeboard-risk.jpg +0 -0
  9. package/docs/images/how-it-works/route-check.jpg +0 -0
  10. package/docs/images/how-it-works/setup-panel.png +0 -0
  11. package/docs/images/how-it-works/ukc-overlay.jpg +0 -0
  12. package/lib/ack-service.js +80 -0
  13. package/lib/ack-store.js +74 -0
  14. package/lib/api/ack-request.js +69 -0
  15. package/lib/api/assets.js +127 -0
  16. package/lib/api/manifest.js +194 -0
  17. package/lib/api/mvt.js +92 -0
  18. package/lib/api/query-request.js +127 -0
  19. package/lib/api/route-request.js +221 -0
  20. package/lib/api/routes.js +215 -0
  21. package/lib/api/ukc-tile-changes.js +199 -0
  22. package/lib/api-wiring.js +88 -0
  23. package/lib/block-keeper.js +53 -0
  24. package/lib/config-migrate.js +68 -0
  25. package/lib/config-presets.js +49 -0
  26. package/lib/config-schema.js +375 -0
  27. package/lib/config.js +185 -0
  28. package/lib/engine/acks.js +171 -0
  29. package/lib/engine/departure-window.js +106 -0
  30. package/lib/engine/envelope.js +364 -0
  31. package/lib/engine/escape.js +65 -0
  32. package/lib/engine/explain.js +119 -0
  33. package/lib/engine/fan.js +139 -0
  34. package/lib/engine/footprint.js +59 -0
  35. package/lib/engine/grounding-detect.js +108 -0
  36. package/lib/engine/hysteresis.js +92 -0
  37. package/lib/engine/lookahead.js +262 -0
  38. package/lib/engine/notify.js +71 -0
  39. package/lib/engine/query.js +57 -0
  40. package/lib/engine/route-check.js +292 -0
  41. package/lib/engine/route-repair-search.js +233 -0
  42. package/lib/engine/route-repair.js +349 -0
  43. package/lib/engine/schedule.js +94 -0
  44. package/lib/engine/trajectory.js +82 -0
  45. package/lib/engine/ukc-reach.js +369 -0
  46. package/lib/engine/ukc-tile-geometry.js +401 -0
  47. package/lib/engine/ukc-tiles.js +249 -0
  48. package/lib/engine/verdict.js +96 -0
  49. package/lib/engine/work.js +15 -0
  50. package/lib/escape-search.js +124 -0
  51. package/lib/foundation/antimeridian.js +92 -0
  52. package/lib/foundation/durable-file.js +86 -0
  53. package/lib/foundation/float32.js +21 -0
  54. package/lib/foundation/geo.js +229 -0
  55. package/lib/foundation/geometry.js +449 -0
  56. package/lib/foundation/memory.js +15 -0
  57. package/lib/foundation/public-text.js +40 -0
  58. package/lib/foundation/state.js +31 -0
  59. package/lib/foundation/stats.js +35 -0
  60. package/lib/index-loader.js +360 -0
  61. package/lib/index-startup.js +52 -0
  62. package/lib/index.js +141 -0
  63. package/lib/ingest/cell-reader.js +117 -0
  64. package/lib/ingest/cell-source.js +150 -0
  65. package/lib/ingest/cells.js +102 -0
  66. package/lib/ingest/datum.js +46 -0
  67. package/lib/ingest/enc-bounds.js +95 -0
  68. package/lib/ingest/enc-wasm.js +283 -0
  69. package/lib/ingest/features.js +2 -0
  70. package/lib/ingest/s57-geojson.js +345 -0
  71. package/lib/ingest/wfs-fetch.js +256 -0
  72. package/lib/ingest/wfs.js +269 -0
  73. package/lib/livechart/cell-log.js +88 -0
  74. package/lib/livechart/chart-blocks.js +51 -0
  75. package/lib/livechart/csb-export.js +40 -0
  76. package/lib/livechart/discrepancy.js +75 -0
  77. package/lib/livechart/ndjson.js +57 -0
  78. package/lib/livechart/note-schedule.js +58 -0
  79. package/lib/livechart/posterior.js +224 -0
  80. package/lib/livechart/rebind.js +18 -0
  81. package/lib/livechart/restore.js +78 -0
  82. package/lib/livechart/sample-log.js +68 -0
  83. package/lib/livechart/saved-state.js +115 -0
  84. package/lib/livechart/settle.js +128 -0
  85. package/lib/livechart/soundings.js +82 -0
  86. package/lib/livechart/state-files.js +339 -0
  87. package/lib/livechart-service.js +295 -0
  88. package/lib/model/allowances.js +88 -0
  89. package/lib/model/fmi.js +268 -0
  90. package/lib/model/integrity.js +137 -0
  91. package/lib/model/level-regimes.js +66 -0
  92. package/lib/model/position.js +16 -0
  93. package/lib/model/uncertainty.js +19 -0
  94. package/lib/model/vessel.js +53 -0
  95. package/lib/model/water-level.js +255 -0
  96. package/lib/monitor.js +386 -0
  97. package/lib/nav-inputs.js +78 -0
  98. package/lib/notifications.js +97 -0
  99. package/lib/query-service.js +162 -0
  100. package/lib/route-service.js +228 -0
  101. package/lib/settings-service.js +192 -0
  102. package/lib/setup-checks.js +124 -0
  103. package/lib/spatial/block-cache.js +376 -0
  104. package/lib/spatial/block-reader.js +113 -0
  105. package/lib/spatial/build-box.js +85 -0
  106. package/lib/spatial/build-items.js +131 -0
  107. package/lib/spatial/build-position.js +97 -0
  108. package/lib/spatial/build-reuse.js +112 -0
  109. package/lib/spatial/build-worker.js +283 -0
  110. package/lib/spatial/chart-index.js +320 -0
  111. package/lib/spatial/chart-position.js +146 -0
  112. package/lib/spatial/hazards.js +153 -0
  113. package/lib/spatial/node-store.js +374 -0
  114. package/lib/spatial/node-values.js +79 -0
  115. package/lib/spatial/polygon-index.js +325 -0
  116. package/lib/spatial/pyramid-blocks.js +324 -0
  117. package/lib/spatial/pyramid-build.js +409 -0
  118. package/lib/spatial/pyramid-regions.js +141 -0
  119. package/lib/spatial/pyramid.js +423 -0
  120. package/lib/spatial/quality.js +38 -0
  121. package/lib/spatial/store.js +303 -0
  122. package/lib/spatial/survey-shadow.js +208 -0
  123. package/lib/spatial/tile-walk.js +154 -0
  124. package/lib/spatial/walk.js +89 -0
  125. package/lib/status-report.js +56 -0
  126. package/lib/tick-publisher.js +68 -0
  127. package/lib/water-level-service.js +128 -0
  128. package/lib/wfs-service.js +404 -0
  129. package/lib/wfs-wiring.js +109 -0
  130. package/lib/wfs-worker.js +50 -0
  131. package/lib/zones.js +61 -0
  132. package/package.json +150 -4
  133. package/public/lookahead-style.json +56 -0
  134. package/public/panel.html +36 -0
  135. package/public/panel.js +182 -0
  136. package/public/routecheck-style.json +30 -0
  137. package/public/runtime.html +10 -0
  138. package/public/runtime.js +469 -0
  139. package/public/setup-model.js +152 -0
  140. package/public/setup.html +98 -0
  141. package/public/setup.js +649 -0
  142. package/public/ukc-shared.js +404 -0
  143. package/public/vendor/plotterext-bus/LICENSE +21 -0
  144. package/public/vendor/plotterext-bus/chunk-UZTRWLMT.js +139 -0
  145. package/public/vendor/plotterext-bus/chunk-WV66EF3N.js +375 -0
  146. package/public/vendor/plotterext-bus/chunk-WWNNVR3K.js +402 -0
  147. package/public/vendor/plotterext-bus/extension.js +37 -0
  148. package/public/widget.html +23 -0
  149. package/public/widget.js +84 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,796 @@
1
+ # Changelog
2
+
3
+ All notable changes to signalk-underkeel are documented here.
4
+
5
+ ## [0.2.0] - 2026-10-27
6
+
7
+ ### Added
8
+
9
+ - Inland ENC cells (issue #50). A cell whose name and `DSID_INTU` give no usage band 1–6, as
10
+ Inland ENC cells give 7, takes its band from its compilation scale by the IHO S-65 ranges:
11
+ Rijkswaterstaat's Waddenzee cells, 1:2 000, are berthing. Before they were rejected ("usage
12
+ band unknown"). The Inland ENC low-water references (VERDAT 31, 36, 38) and approximate LAT
13
+ (42) count as low-water datums, so with no water-level source chart datum applies on them as
14
+ on LAT. Cells are found down to six folders below a folder holding the exchange set's
15
+ `CATALOG.031`, so an unzipped Inland ENC download (`ENC_ROOT/1R/7/<cell>/<cell>.000`) can be
16
+ set as the cells directory as it is.
17
+
18
+ ### Changed
19
+
20
+ - Survey shadow: a charted shoal beyond the boat's buffer counts by the chance the chart is off
21
+ by its distance, and now also by the chance that the water charted closer is off as far: what
22
+ that water's survey measured lies under the boat unless it is. A CATZOC D drying flat 300 m
23
+ beyond 250 m of CATZOC B water no longer counts, nor do its no-coverage or unassessed flags;
24
+ in D water alone nothing changes. The explanation names the water that bounded it ("behind
25
+ 30 m of water placed ±50 m"), and the navigation-safety schema carries it as
26
+ `chartPosition.shadow`. The UKC overlay does not apply it yet and stays at least as severe.
27
+ - Two cells, or two survey-quality zones, that meet along one line with their vertices split
28
+ differently, overlapping or up to 0.5 m apart now cover the leaves on that seam. Before,
29
+ every such leaf read no coverage or unassessed. The index is rebuilt once (pyramid version 11).
30
+
31
+ ## [0.1.0] - 2026-10-25
32
+
33
+ ### Added
34
+
35
+ - Setup steps in Freeboard, opened with **Open setup** in the Under-keel details panel (also
36
+ `/plotterext/signalk-underkeel/setup.html`): the boat on a side view whose keel, safety margin and
37
+ sounder can be dragged, with what the plugin adds on its own (squat, waves), the water-level
38
+ source with the one fitting the charts' vertical datum marked, a warning style and the optional
39
+ features, with a setup check. It reads and saves through the admin-only `GET` and
40
+ `POST /settings`; a save is a patch checked against the schema, and the server's restart
41
+ callback writes it and restarts the plugin.
42
+ - Warning styles Early, Balanced and Late set the look-ahead thresholds, windows and distance;
43
+ Balanced is the earlier default. An expert value overrides its field.
44
+ - The admin form asks for the cells directory, draft, margin, water-level source, warning style
45
+ and optional features; **Show expert settings** opens 29 more fields and a
46
+ feature's fields appear once it is enabled. Its description lists the setup check, and the
47
+ draft and water-level fields say what Signal K and the charts state. Admin UIs before Signal
48
+ K 2.32 get every field at once.
49
+ - The configuration is versioned (`configVersion: 2`). The first start after an update keeps
50
+ the old configuration as `config-v1.json` in the plugin data directory and removes the
51
+ look-ahead values the old form filled in with their defaults; the plugin behaves as before.
52
+ - Depth areas and contours are placed by the chart's own drawing (0.5 mm at the cell's
53
+ compilation scale, 6 m at 1:12 000), as land already was, instead of by the survey's CATZOC
54
+ position accuracy; soundings and point dangers keep CATZOC. A record NOAA marks approximate
55
+ (QUAPOS 4) widens the drawing to four times its σ, not to the survey's. Over the 1939 CATZOC C
56
+ water at Bakers Haulover Inlet every cell within about 300 m of the shore or a drying contour
57
+ had read `danger` for a 0.9 m draft; now only those within reach of the zone's charted
58
+ obstructions do. An `M_CSCL` area compiled at a smaller scale widens the drawing only on the
59
+ index leaves it reaches: a 1:80 000 area in a 1:12 000 cell spreads the contours and shoreline
60
+ inside it by 40 m, and a record not surveyed there by 160 m, while the rest of the cell keeps
61
+ 6 m. A sounding inside a shallower drawn area keeps its survey spread when its tile splits.
62
+ The saved index is rebuilt (pyramid version 10).
63
+ - The index is built around the vessel: **Index box around the vessel (km)** (`boxRadiusKm`,
64
+ default 10) builds only the S-57 cells reaching a box around the vessel and rebuilds it as
65
+ the vessel moves, as the Traficom WFS box does. Outside the box the plugin reports no
66
+ coverage. Cells are picked by their extent, read from the `.000` without GDAL. The 698-cell
67
+ NOAA set no longer builds whole at start (over 15 minutes); a 10 km box takes 22 s on x86.
68
+ Tiles are built 2 km past the box, flagged no coverage but keeping their depth, so a hazard
69
+ just outside still counts for a footprint just inside; cells are read to 6 km past the box.
70
+ A start loads the saved box index while its cells, box and leaf zoom match and otherwise
71
+ rebuilds it in its box, never from every cell. A missing cells directory, or one that holds no
72
+ cell while the saved index holds S-57 cells, as an unmounted drive leaves it, keeps the saved
73
+ index at start and the index in use at a refresh, instead of rebuilding from Traficom WFS
74
+ depths alone or dropping the index. A torn or missing saved WFS cell is left out of the start
75
+ and downloaded again at the first check, and the saved box index stays in use meanwhile. A
76
+ box whose index could not be put in use is built and handed over again after 5 minutes.
77
+ `GET /status` reports the box under `chartBox`. `boxRadiusKm: 0` indexes every cell; a radius
78
+ under 2 km is raised to 2.
79
+ - `indexDir` is owned by the plugin: a directory holding anything but an index is refused
80
+ rather than replaced, before any build starts and with the foreign entry named, and the box
81
+ service then downloads and builds nothing until it is set right. A trailing separator is
82
+ accepted, and staging or backup copies left by a failed save or a restart are removed.
83
+ - S-57 ENC cells are read as delivered: **ENC cells directory** takes `.000` files with their
84
+ `.001`, `.002` … updates, also inside an exchange set's `ENC_ROOT` folders, read in the index
85
+ worker with gdal3.js (GDAL compiled to WebAssembly), now a runtime dependency. No export step
86
+ and no intermediate files. A saved
87
+ index is kept while each cell's files keep their names, sizes and modification times. The
88
+ edition comes from the base cell's DSID, since GDAL reports 0 once NOAA updates are applied.
89
+ The 12 NOAA cells around Miami build in 19 s at leaf zoom 18 on x86.
90
+ - App Store screenshots: `package.json` lists six of the docs images under
91
+ `signalk.screenshots`, and the package ships them and the README illustration.
92
+ - `GET /status?summary` leaves out `index.cells` and `waterLevel.datums`, which grow with the
93
+ cells: 22.7 kB with 300 cells against 237 B. It keeps every field the Freeboard panel and
94
+ runtime read.
95
+ - Freeboard UI as Plotter Extensions contributions, served from `/plotterext/signalk-underkeel/`:
96
+ a background runtime, look-ahead and route-check data overlays, a status widget, a details
97
+ panel and a toolbar button. Freeboard core is unchanged.
98
+ - Traficom WFS depths (off by default): depth areas and soundings for a box around the vessel,
99
+ re-downloaded as it moves and indexed in a worker thread, as a band-1 cell flagged
100
+ `NOT_FOR_NAVIGATION`; water it alone covers is never `normal`, `ok` or `clear`.
101
+ - Survey quality at zone boundaries: a leaf across the shared edge of two assessed `M_QUAL`
102
+ zones takes the worse zone's σ instead of the unassessed σ and flag, when the zones share
103
+ the edge vertex for vertex. Gaps, overlaps and differently split edges stay `UNASSESSED`.
104
+ - Proposal: JSON Schemas `csb-cell.json` and `csb-cell-set.json` and an RFC draft for
105
+ aggregated crowdsourced depth cells. This release adds no crowdsourced-depth ingest.
106
+ - Contract (M6): JSON Schemas of the navigation-safety contract in `schemas/navigation-safety/`,
107
+ contract tests for this plugin and a stub second provider, and RFC drafts for the Signal K
108
+ paths and the Plotter Extensions `services` section.
109
+ - Route repair and departure window (M5): `POST /route-repair` suggests waypoints around
110
+ failing legs (Theta\* on a lazy cost grid, simplified only where legs still pass);
111
+ `POST /departure-window` returns the departures over the horizon in which every leg is ok.
112
+ - Living chart (M5, off by default): own soundings through a quality gate and datum reduction
113
+ update per-cell posteriors; two-pass discrepancies lower the cell for every query and
114
+ become Signal K notes; `GET /livechart/discrepancies` and an IHO CSB export.
115
+ - Dynamics (M4): CTRV fan of five members scored as one hull per step, GNSS-based position
116
+ σ, along-track footprint growth, escape heading (`navigation.underKeel.escapeHeading`) and
117
+ state hysteresis.
118
+ - Position integrity (M4): dead reckoning from heading, speed through water and a learned
119
+ current against GNSS; divergence, a poor fix or HDOP above 4 inflate σ_pos and raise
120
+ `notifications.navigation.positionIntegrity`.
121
+ - Acknowledged passages (`GET/POST/DELETE /acks`) and mooring zones from Signal K regions,
122
+ which publish warn and alarm as alert with the reason (M4).
123
+ - Optional grounding detector, off by default, the only writer of `notifications.grounding`
124
+ (M4).
125
+ - Probabilistic UKC (M3): P(UKC < 0) per footprint from CATZOC σ, draft, Barrass squat, heel,
126
+ wave allowance and water level; risk thresholds for alert / warn / alarm; an explanation
127
+ object on every notification and route-check leg; `clearanceSigma` and `risk` deltas.
128
+ - Water-level sources (M3): manual, Signal K tide and FMI forecast with tide-gauge blending;
129
+ per-cell vertical datum mapping; chart-datum fallback with a reason after 30 minutes stale.
130
+ - `POST /query` for point and polygon UKC, and UKC vector tiles with a MapLibre style,
131
+ declared as a `plotterExtensions` data overlay (M3).
132
+ - Deterministic look-ahead (M1): straight cone along COG, chart-datum UKC with a fixed margin,
133
+ `navigation.underKeel.*` deltas, `notifications.navigation.underKeel`, `GET /status`,
134
+ `GET /envelope`, and a `plotterExtensions` manifest resource.
135
+ - Corridor route check (M2): `POST /route-check` with per-leg `ok` / `marginal` / `fail` /
136
+ `unverified`, ETAs, the shallowest charted depth and hazard, and chart-edition provenance.
137
+ - Development plan in `docs/DEVELOPMENT-PLAN.md`.
138
+ - Chart index library: S-57 GeoJSON ingest with cell provenance, CATZOC → σ table,
139
+ min-depth pyramid with a fast-check conservativeness property test, hazard R-tree, and
140
+ on-disk index format.
141
+
142
+ ### Changed
143
+
144
+ - `scripts/enc-to-geojson.sh` is removed and **ENC cells directory** no longer reads its GeoJSON
145
+ folders: it reads the original `.000` cells. A folder named like a cell without one is
146
+ reported as skipped. The plugin test fixtures are now S-57 cells written by
147
+ `fixtures/s57/generate.js`.
148
+ - Chart position is graded (plan §4.3). A charted object beyond a footprint and its buffer
149
+ counts with its P(UKC < 0) times Φ(−g/σP), the chance the chart is off by its distance g,
150
+ instead of in full within 2σP. The depth reported under a footprint is the depth charted
151
+ there, so a route leg no longer fails on land within 500 m of a CATZOC C shore, and points in
152
+ assessed water are no longer burned as discs. Flags still count within 2σP.
153
+ - Land and shoreline objects are placed by their own accuracy: the cell's compilation scale,
154
+ or the survey's σP on edges and nodes whose QUAPOS says they are not surveyed.
155
+ The reader takes those records from GDAL's primitive layers (Edge, ConnectedNode,
156
+ IsolatedNode).
157
+ - UKC tiles mark cells raised only by a nearby cell's chart position with `reach`, which the
158
+ style draws fainter, so the solid classes follow the chart's own depth areas.
159
+ - Explanations of a deciding tile beyond the footprint give its distance, its position σ and
160
+ the chance it lies under the keel.
161
+ - A look-ahead footprint scored beyond the warn window covers the hulls of the steps it skips,
162
+ also where the 400-footprint budget places it off the step grid, so in a turn its P is never
163
+ below scoring every step.
164
+ - The index splits tiles no finer than 1 mm at each cell's compilation scale: an overview
165
+ cell's coastline stops at z14 instead of z20. The 25 NOAA cells around Miami build in 94 s
166
+ instead of over 15 minutes; a stopped tile takes the shallowest depth it holds.
167
+ - Pyramid format version 8: an index built by an earlier version is rebuilt at start.
168
+ - A Traficom WFS refresh builds only the z10 index roots that the old or new box reaches, or a
169
+ cell with a new DSID, and copies the other roots from the saved index, which now keeps each
170
+ cell's reach in `reach.json`; the result is byte-identical to a full build. With 16 copies of
171
+ the Nauvo pair (32 cells) and the real 10 km box moved 5 km, the refresh built 4 of 12 roots:
172
+ 30.8 → 11.8 s of worker time at leaf zoom 20 and 5.6 → 2.7 s at 18 on x86. Where both boxes
173
+ reach every ENC root, as with the Nauvo pair alone, every root is still built.
174
+ - The Traficom WFS download asks each layer's count first (`resultType=hits`), then reads its
175
+ pages sorted by `IDENTIFIER`, up to 4 requests at once across the three layers. A box whose
176
+ count is over 50 000 features is refused before any page is fetched, and a layer whose pages
177
+ hold more or fewer features than the count, or the same feature twice, fails the download.
178
+ Against the live server the same features came in 5.6 s instead of 8.6 s for a 10 km box off
179
+ Helsinki, 13.1 s instead of 19.3 s for 10 km at Nauvo and 30.4 s instead of 81.7 s for 25 km
180
+ at Nauvo.
181
+ - The gdal3.js ENC reader converts only the layers the index
182
+ reads, one `ogr2ogr` to in-memory GeoJSON each, with the unsurveyed-edge filter run in GDAL,
183
+ instead of one `ogrinfo -json -features` of every layer: 2.0–2.9× faster on 12 NOAA cells
184
+ with the same features (US5FL61M 4.2 → 1.6 s, 510 → 270 MB RSS). It finds its WebAssembly
185
+ files from the package location rather than the working directory, and a cell GDAL cannot
186
+ open rejects with an `Error`.
187
+ - The index built in a worker, at start or for a WFS box, is posted to the main thread with its
188
+ pyramid columns moved, not copied, instead of being read back from disk: the longest
189
+ event-loop block at the handover fell from 52–61 to 21–23 ms for the Nauvo pair and a 10 km
190
+ box at leaf zoom 20, and from 258–292 to 68–97 ms with 32 cells, on x86.
191
+ - UKC tiles keep each tile's cells and neighbour reach between requests, in typed arrays up to
192
+ 8 MiB, and re-class only the few value kinds of a tile after a water-level move; the cache
193
+ is emptied by a new index and a tile is walked again when an own sounding changes a cell in
194
+ it. A 40-tile z14 view over the Nauvo cells refreshes in 29 ms instead of 86 ms on x86, and
195
+ a tile the change feed lists after a 1 cm fall takes 0.74 ms instead of 2.35 ms (p50).
196
+ - `pyramid.bin` (format version 6, rebuilt once) holds the zooms to 15 in one gzip member and the
197
+ finer nodes in one member per z12 tile, and a loaded index reads those blocks when a query
198
+ first reaches them, keeping up to 32 MB of them and those around the vessel and 300 s ahead
199
+ on its course. A block not loaded reads as no coverage with bounds no loaded tile exceeds, so
200
+ no answer is ever safer than with it loaded. 64 copies of the Nauvo pair (13.5 M nodes) on
201
+ x86: RSS after start 579 → 94 MB, a 150 km passage at 10 m/s peaks at 154 MB instead of
202
+ 602 MB with identical states on all 15 000 ticks; the first tick reading a block takes 13.5 ms
203
+ (8.5 ms held whole), steady ticks are unchanged.
204
+ - The index build in the worker builds the pyramid one z10 root at a time, from only the cells
205
+ reaching it, on up to four threads, with output byte-identical to a build of all cells at
206
+ once. Sixteen copies of the Nauvo pair (3.3 M nodes) on x86: peak RSS 817 → 481 MB on one
207
+ thread; 27.6 → 13.4 s on three threads (974 MB). The default is one thread per core but one,
208
+ at most four and at most one per GiB of RAM.
209
+ - The hazard R-tree is packed in typed arrays: 1 M soundings take 47 MB of tree instead of
210
+ 289 MB and build in 1.3 s instead of 3.1 s on x86. Hazards at the same depth and distance from
211
+ a query are listed in catalogue order.
212
+ - The pyramid's node store is a sorted tile-key column per zoom level instead of a `Map`, and
213
+ `pyramid.bin` is written in that order, so loading uses the inflated
214
+ columns in place. Two Nauvo cells: load 101 → 22 ms, resident +43 → +16 MB; the same 16
215
+ times over (3.3 M nodes): load 2.4 s → 0.24 s, +490 → +148 MB, lookup 524 → 135 ns. A store
216
+ is no longer limited to the 16.7 M nodes of a V8 `Map`.
217
+ - `pyramid.bin` stores its columns gzip-compressed, 13× fewer bytes written to the SD card per
218
+ rebuild (7.5 MB → 0.56 MB for two Nauvo cells at leaf zoom 20); an index saved by an earlier
219
+ version of the plugin is rebuilt once at start.
220
+ - The index build tests each area against a tile through a per-polygon box and edge grid and
221
+ decides "reaches" and "contains" in one boundary pass, with the same nodes byte for byte:
222
+ two Nauvo cells at leaf zoom 20 build in 1.9 s instead of 23.4 s on x86.
223
+ - The living chart moves onto a rebuilt WFS index in slices of 1 000 cells, one turn of the
224
+ event loop each, with the index swapped in during the turn that finishes the move; when only
225
+ the WFS cell changed, only the cells near the old and new box are re-judged. With 19 574
226
+ cells the handover blocked the event loop for 123–153 ms on x86 at leaf zoom 18; the longest
227
+ block is now 53–71 ms.
228
+ - The next Traficom WFS box is fetched once the edge ahead is closer than SOG × 1.5 × the last
229
+ download-and-build time plus the look-ahead's reach and the band inside the edge where a
230
+ footprint can read no coverage (the 500 m position buffer cap plus 1 860 m of chart reach,
231
+ counted up to half the radius), as well as at half the radius, and is centred that far ahead
232
+ along COG (at most 0.8 × the radius). With 10-minute rebuilds at 25 kn the vessel was 5.4 km
233
+ past the old box when the new one was handed over; with the look-ahead's reach alone it was
234
+ 2.3 km inside it, and the band starts the refresh up to 2.36 km earlier. Without the band, in
235
+ CATZOC C or D water the look-ahead read no chart coverage for the last 0.5–1.5 km before each
236
+ handover. The last refresh time is saved in `box.json`.
237
+ - The Traficom WFS download, parse, clip and cell write run in the index build worker with the
238
+ build, so the main thread only moves the staged index into place and loads it. With the
239
+ 10 km box (one 22 MB page) the server's event loop was blocked for 336–420 ms and 209–277 ms
240
+ per refresh on x86; now the longest block is the 67–83 ms handover.
241
+ - Living-chart saves: the accepted soundings are appended to `soundings.ndjson` every minute
242
+ (rewritten with the newest 20 000 when it reaches twice that). The cells are saved every
243
+ 10 minutes, and within 10 s of an adjustment being added or moving a 5 cm or 1 cm σ step:
244
+ those sounded since the last save are appended to `cells.ndjson`, one line each, and the file
245
+ is rewritten with the current cells once it would hold more than twice as many lines as the
246
+ larger of its cell count and 1 000, or after cells are dropped. `livechart.json` holds the
247
+ zoom and the adjustments and is rewritten only when they change. Saves run on a timer instead
248
+ of inside the depth-delta callback. Before, `livechart.json` with
249
+ all 20 000 soundings was rewritten every minute: 192 MB/h of SD-card writes and a 20–46 ms
250
+ save in the delta callback; and at anchor every cell ever sounded was rewritten every
251
+ 10 minutes. A `livechart.json` that still holds soundings or cells loads, and they move to
252
+ `soundings.ndjson` and `cells.ndjson` at the next save.
253
+ - The living chart keeps at most 10 000 cells it may drop: past that, those sounded longest ago
254
+ are dropped until 9 000 remain. A cell is never dropped while it has an adjustment or waits
255
+ for its chart block. A cell that has read 1σ or more shallower than the chart and has not yet
256
+ had 5 samples over 2 passes is capped on its own the same way, so a shoal waiting for its
257
+ second pass is not crowded out by ordinary cells, and a steady error that marks every cell of
258
+ a passage cannot grow them without end. A dropped cell sounded again starts from the chart. `GET /status` counts the dropped cells as
259
+ `livechart.dropped`.
260
+ - Living-chart notes are rewritten when the cell's adjusted depth drops a 5 cm step or its σ
261
+ rises a 1 cm step, at most once per cell every 5 minutes (the latest values after that, and
262
+ on stop), and show the depth floored to 5 cm and σ raised to the next cm. Before, every
263
+ change of the adjustment rewrote the note: 6 240 note writes in a 2 h simulated run.
264
+ - UKC vector tiles of 1 kB or more are sent gzipped with `Content-Encoding: gzip` when the client
265
+ accepts it, and every tile carries `Vary: Accept-Encoding`; Signal K's compression skips the
266
+ vector-tile type. A 40-tile z14 viewport over the Nauvo cells went from 279 kB to 52 kB, at
267
+ 0.19 ms of gzip per tile on a laptop.
268
+ - Route checks, repairs, departure windows and `POST /query` run one at a time, with at most four
269
+ waiting and 503 with `Retry-After` beyond that; a request whose client disconnects, or that is
270
+ running when the plugin stops, is abandoned at its next pause. Ten concurrent repairs of a
271
+ 100-leg route over the Nauvo cells delayed the event loop by up to 264 ms on a laptop (about
272
+ 1 s on a Raspberry Pi 4) and now by at most 28 ms; abandoned requests ran to the end, holding
273
+ the old chart index after a stop.
274
+ - Route repair yields to the event loop every 256 cells its search expands, after each
275
+ simplification check and between the corridor pieces of each check, not only between legs. A
276
+ search that exhausts its grid around an enclosed goal blocked the server for 105–109 ms on a
277
+ laptop (about 0.4 s on a Raspberry Pi 4); its longest slice is now 3.4–5.2 ms.
278
+ - Route checks split a leg into pieces of max(1 km, 4 × corridor half-width) instead of 1 km,
279
+ and check the great circle separately only where it strays more than max(10 m, r/4) from the
280
+ rhumb line. A 12 km leg at xteLimit 2000 took 129 ms on a laptop and takes 39 ms; four such
281
+ legs 402 → 115 ms. Corridors at the default width are unchanged in number.
282
+ - The departure window stops checking a departure at its first failing leg, whose status the
283
+ remaining legs cannot change. On a 100-leg route over the Nauvo cells that fails early,
284
+ 9 991 leg checks and 1.9 s became 91 checks and 54 ms on a laptop, with the same steps.
285
+ - The departure window reuses a leg's `ok` at any higher water level and its `fail` at any lower
286
+ one, with the same σ, when `probability` is at least 1e-3; below that each level is checked
287
+ directly. A 60-leg route over a 24 h ramp went from 3 793 leg checks and 347 ms to 2 219 and
288
+ 212 ms on a laptop, with the same steps.
289
+ - The navigation-safety contract schemas in `schemas/navigation-safety/` are licensed under
290
+ Apache-2.0, so other plotters and providers can adopt the contract; the plugin stays EUPL-1.2.
291
+ - The request schemas bound `sector` (1..90°), `ttl` (1 s..30 days), `notificationId` (200
292
+ characters), speeds, drafts, `bufferMetres`, `xteLimit` and `probability` as the plugin
293
+ does, so a request that validates is no longer refused for those fields; size budgets are
294
+ listed in `schemas/navigation-safety/README.md`.
295
+ - Look-ahead and query tile walks measure distances with `Math.sqrt` instead of `Math.hypot`,
296
+ widen every reach by 1e-12 so a 1-ulp rounding can only add a tile, and reuse one tile
297
+ rectangle and result per walk. On the Nauvo test route at 6 kn the tick median fell from
298
+ 2.6 to 1.7 ms and p95 from 7 to 3.9 ms (x86), with the same states, risks and footprints on
299
+ all 2296 ticks.
300
+ - A look-ahead footprint stops reading the chart once it finds charted land at P = 1, and is
301
+ read again in full only where the state turns on its coverage. Alarm ticks on the Nauvo route fell from 2.6
302
+ to 2.2 ms median, and a tick after a 2 km GNSS jump from 770 to 270 ms (x86).
303
+ - Look-ahead hull rectangles compute each point's ellipsoid scale and each bearing's sine and
304
+ cosine once instead of in six `project()` calls, with the same coordinates: footprint geometry
305
+ 0.25 → 0.21 ms per 6 kn tick (x86).
306
+ - Beyond the 120 s warn window the look-ahead scores only every k-th step, the most that still
307
+ leaves neighbouring footprints touching (every 3rd at 6 kn, every 20th at 1 kn), and scores the
308
+ skipped steps where one of those footprints is the first to reach P 5 %, P 1 % or a coverage
309
+ gap, so `timeToShoal` and the reason keep the 3 s time. On the Nauvo route at 1 kn a tick
310
+ scores 57 footprints instead of 361, the median fell from 30 to 2.7 ms and the envelope from
311
+ 17 to 5 kB (x86); states, risks, clearances, times to shoal, reasons and escape headings were
312
+ the same on every tick at 1 kn, 6 kn and with a 5 NM horizon (90 → 20 ms).
313
+ - `GET /envelope` drops outline vertices within 1 cm of the line through their neighbours. With
314
+ a 5 NM horizon (400 footprints) the envelope fell from 19.5 to 3.5 kB median and 21.4 to
315
+ 5.6 kB at most, back within the 15 kB budget; at 6 kn from 4.1 to 2.5 kB.
316
+ - The escape heading is searched after the tick's deltas are published, so a tick blocks the
317
+ server in two shorter pieces; after a tick over 250 ms the next search is skipped, after a
318
+ search over 250 ms the next one waits 3 s, and the plugin status says so. With a 5 NM horizon
319
+ the longest tick fell from 264 to 185 ms (x86), the search following in up to 27 ms.
320
+ - `notifications.navigation.underKeel` is sent at once when its state, the kind of reason or the
321
+ named hazard changes, and while those hold its message with a new countdown at most every 30 s.
322
+ The countdown in the message made it go out every 3 s: on the Nauvo route at 6 kn 365
323
+ notifications in 2296 ticks with 28 state changes, now 77.
324
+ - `navigation.underKeel.*` values other than `state` and `envelopeRev` are sent when they change
325
+ and at least every 10 s, and the plugin status only when its text changes. On the Nauvo route
326
+ at 6 kn the values sent fell from 18 733 to 7 063 in 2296 ticks (507 → 203 B per tick), and
327
+ `setPluginStatus` calls from 2297 to 329.
328
+ - Below the low speed `navigation.underKeel.envelopeRev` no longer bumps while GPS noise moves
329
+ the drawn envelope less than 5 m and no class or number in it changes. At rest with 1 m of
330
+ position noise it bumped on 599 of 600 ticks, so every Freeboard fetched the envelope and
331
+ redrew its overlay once a second; now 0 (153 with 2 m of white noise).
332
+ - The look-ahead buffer k_p · σ_pos stops at 500 m. Beyond that the state is at least `warn`
333
+ with the reason "position uncertainty N m" and the integrity monitor's reasons, and no escape
334
+ heading is searched. After a 2 km GNSS jump in water without land a tick took 0.4 to 3.2 s
335
+ (x86) and could still read `normal`; it now takes 3 to 27 ms and reads `warn`.
336
+ - A depth query no longer tests the tiles under a tile that lies wholly within its buffer of
337
+ the footprint or polygon. A 499-vertex `POST /query` polygon of 500 m radius with a 2 km
338
+ buffer took 198 ms, now 48 ms (x86); jagged polygons gain nothing (124 → 128 ms).
339
+ - The status widget changes the page only when a value it shows changes. With three Signal K
340
+ values a second and steady readings it made 549 DOM changes and 99 layouts a minute; now
341
+ none.
342
+ - The extension pages, scripts and styles under `/plotterext/signalk-underkeel/` carry an ETag
343
+ and are answered 304 when the browser holds them, still with `Cache-Control: no-cache`. A
344
+ Freeboard reload fetched 56.2 kB of them and now 12.7 kB; a first load 57.5 kB and now
345
+ 36.3 kB, since the three pages share four scripts.
346
+ - `npm test` runs its 1087 tests in about 51 s instead of about 4.5 minutes on a laptop, with
347
+ every property test, the replay and the safety-invariant suites at full depth, also in the
348
+ Signal K registry's sandboxed run. Jest's stock Node environment builds each test file's
349
+ context from a proxy, so every lookup of `Math`, `Number` and typed arrays in the chart and
350
+ engine code went through an interceptor: the replay test took about 70 s for code that runs
351
+ in about 4 s in plain Node, and now takes about 3 s. The tests run in
352
+ `__tests__/helpers/node-realm-environment.js`, the same environment on a plain vm context
353
+ (`vm.constants.DONT_CONTEXTIFY`, Node 22.8 or later; older Node runs the stock one), and
354
+ property tests assert once per run instead of once per element. A test may make at most
355
+ 20 000 `expect()` calls, and CI fails `npm run verify` when the test run takes over 120 s
356
+ (`UNDERKEEL_TEST_BUDGET_S`). `jest-environment-node` is a direct dev dependency.
357
+
358
+ ### Fixed
359
+
360
+ - The chart index is built in a worker thread at start too, as it already was for Traficom
361
+ WFS boxes; meanwhile the engine is `off` with the reason `building chart index`. `start()`
362
+ built it on the main thread, which froze the whole Signal K server for 24 s with two Nauvo
363
+ cells at leaf zoom 20 on x86 (about 1.5 min on a Raspberry Pi 4) on the first start, after a
364
+ cell or format change and when the WFS source was toggled. A saved index over 1 MB is read
365
+ and inflated off the event loop too (`off` with `loading chart index`): 3.3 M nodes blocked
366
+ `start()` for 2.2 s, now 6 ms and at most 50 ms per event-loop turn.
367
+ - A saved chart index whose files cannot be read or parsed is rebuilt from the configured
368
+ cells at start, with the read error in the index reason. An index left empty by a power cut
369
+ during a save kept the engine `off` with "chart index failed: Unexpected end of JSON input"
370
+ on every later start until **Rebuild index at start** was set. Index files and their
371
+ directories are now fsynced before and after the rename that commits them.
372
+ - The index build worker runs with a heap limit of a quarter of the RAM (256 MB to 2 GB);
373
+ its root threads, on machines with 2 GiB or more, share a second limit of the same size.
374
+ An oversized build fails with "index build stopped at the N MB worker heap limit" in the
375
+ WFS status and the previous index stays in use; before, it could grow until the kernel ended
376
+ the Signal K server on a 1 GB Pi 3 or Cerbo GX. A worker that exits without a result now
377
+ fails the build instead of leaving the WFS refresh busy for good.
378
+ - `acks.json` and `livechart.json` are flushed to the disk before the rename that replaces
379
+ them, and their directory after it. Without the fsync a power cut could leave an empty
380
+ `livechart.json` on filesystems that do not flush on rename, and the plugin then started
381
+ without its confirmed shoals.
382
+ - Route-check corridors contain every point within the corridor half-width of the leg. They
383
+ were drawn with a spherical bearing in the ellipsoid's tangent plane and missed points at the
384
+ edge by up to 0.3 % of the width (0.12 m at the default ±40 m at the equator); they are now
385
+ drawn on the ellipsoid's bearing and 1/256 wider. Over the Nauvo cells 1 of 609 legs at the
386
+ default width went from `marginal` to `fail` (a 0 m depth area now in reach).
387
+ - `POST /query` is also refused when the polygon's vertices times its box widened by the buffer
388
+ exceed 150 km². A 499-vertex ring with a 2 km buffer fitted the 25 km² limit and blocked the
389
+ server for 0.47 s on a laptop (about 2 s on a Raspberry Pi 4); within both limits the slowest
390
+ query measured over the Nauvo cells took 16 ms.
391
+ - An index build stopped mid-write, by an abort or a crash, no longer leaves its half-written
392
+ staging directory beside the chart index for good: an aborted WFS build removes its own once
393
+ the worker has exited, and loading an index removes any staging directory left by a
394
+ process that has exited.
395
+ - Route check: long legs are checked along the rhumb line as the chart draws it, and along
396
+ the great circle where that strays more than 10 m from it. Pieces were stepped on a fixed
397
+ flat-earth bearing, which drifted 75 m off the drawn line on a 78 km leg at 60° N and left a
398
+ 12.9 km last piece on a 485 km leg.
399
+ - The look-ahead, route check, route repair and `POST /query` count each index tile within
400
+ their buffer plus k·σP of that tile's assessed survey (k = k_p for the look-ahead, 2 for the
401
+ rest, at most 1 km), since depth areas and lines are not widened when the index is built;
402
+ unassessed and not-for-navigation water adds none and stays `unverified`. A drying area 60 m
403
+ off a leg or a footprint in CATZOC B or C water returned `ok` or `normal` with P = 0, and a
404
+ poor survey anywhere in reach no longer widens the buffer for a well-surveyed rock. A leaf
405
+ only partly in an assessed survey, at a coverage edge or between a B and a U zone, keeps the
406
+ reach of its assessed part.
407
+ - UKC tiles draw each cell at least as bad as any cell within 2·σP of its assessed survey, the
408
+ reach a route check counts: water 60 m from a drying area in CATZOC B or C water was drawn
409
+ `clear` while a route check there failed.
410
+ - `GET /envelope` and own soundings keep longitudes in [-180, 180]: near the antimeridian the
411
+ look-ahead track and segments ran past 180° and are now cut there into features with the same
412
+ properties (RFC 7946), and a transducer lever arm across 180° stored 180.00004° E, which the
413
+ living chart counted in the cell west of 180° instead of the one east of it.
414
+ - Route legs take the water level at their own ends: with FMI, a leg more than 30 km from the
415
+ forecast point gets the fallback level (chart datum, or the last level when lower) and is
416
+ never `ok`, instead of taking the level forecast at the vessel.
417
+ - Departure window: each leg takes the lowest water level until one step after it is sailed,
418
+ so a coarse step no longer reports a window across a low water it did not sample (a 12 h
419
+ step over a semidiurnal tide returned a 24 h window in which a +6 h departure failed).
420
+ - Route repair checks each leg at the time the detours before it bring the boat there, and
421
+ returns the whole repaired route re-checked as `route`. A detour delays the later legs, which
422
+ were reported with their old status although a falling tide could make them fail.
423
+ - Route checks yield to the event loop after each corridor query and are refused above 200 km²
424
+ of corridor (route length × 2 × (xteLimit + planning buffer)); the departure window budgets
425
+ departures × corridor area (1600 km²) instead of departures × length; `POST /query` is refused
426
+ above 25 km² of box and buffer. A 1000-point, 490 km route at xteLimit 2000 blocked the
427
+ server for 2.8 s, and a 500-vertex query with a 2 km buffer for about 1 s.
428
+ - A route request's `departure` must be within a year of now; a far-future time such as
429
+ `+275760-09-13T00:00:00.000Z` parsed and then failed with a `RangeError` message.
430
+ - `navigation.underKeel.clearance` is published as `null` when the look-ahead reaches land,
431
+ never `-Infinity`. In-process subscribers such as signalk-to-influxdb received the raw
432
+ value and the database refused the write; no published number is now NaN or infinite.
433
+ - Two cells meeting at ±180° now cover the index leaves on that edge; read as a shared edge,
434
+ every leaf there was `NO_COVERAGE` and `UNASSESSED`, so any leg or footprint touching 180° was
435
+ `unverified` and a repair across it found no path. A cell ending at 180° with nothing past it
436
+ still leaves a gap. Route repair also takes longitudes the short way round, so its search grid
437
+ across 180° covers the leg instead of the whole world, and `POST /route-check`,
438
+ `/route-repair` and `/departure-window` accept legs across ±180° instead of refusing them.
439
+ - Depth queries near the antimeridian also read the tiles at the other end of the world: a
440
+ footprint or position buffer reaching past ±180° used to miss a rock a few hundred metres
441
+ away on the other side, and a footprint drawn wholly past 180° returned no depth and no flag.
442
+ - A rock or sounding charted inside a swept area keeps its survey's depth σ. The swept σ of
443
+ 0.1 m applied to every tile in the area, so a CATZOC C rock 4 m deep in an 8 m swept fairway
444
+ read P(UKC < 0) = 0.08 % instead of 19 % for a 3 m threshold.
445
+ - A footprint on the shared edge of two adjacent cells of one usage band is covered. Each cell's
446
+ `M_COVR` alone held only part of the index tile on the edge, so the tile read `NO_COVERAGE`
447
+ and route legs along every seam came back unverified.
448
+ - Position buffers, burn discs and footprint offsets reach their full distance on the WGS84
449
+ ellipsoid. They were sized on a sphere and fell short north–south below about 55° latitude,
450
+ by up to 0.7 % at the equator (a 100 m buffer reached 99.3 m).
451
+ - Pontoons, floating docks and hulks (`PONTON`, `FLODOC`, `HULKES`) are read as land, and
452
+ unsurveyed areas (`UNSARE`) as having no depth, so a route leg there is unverified and the
453
+ look-ahead is never normal. `scripts/enc-to-geojson.sh` exports these layers. Before, such an
454
+ area inside a cell's coverage took the depth of any nearby sounding's burn disc; now any
455
+ covered place no depth area reaches has no depth.
456
+ - The saved pyramid format is now version 3, with a column for each node's assessed survey σP,
457
+ and a saved index of an older version is rebuilt at start when cells are configured, so an
458
+ index built before the fixes above is not reused.
459
+ - A rock, wreck or obstruction without `VALSOU` that covers and uncovers (`WATLEV` 4) or is
460
+ subject to inundation (`WATLEV` 6) counts as land, like `WATLEV` 1 and 2. It was taken as
461
+ 0 m at chart datum, deeper than a hazard that dries at low water.
462
+ - A cell directory that is a symbolic link is indexed; it was skipped without a word, at start
463
+ and in Traficom WFS rebuilds. Entries in the cells directory named like a cell that are not a
464
+ directory, such as an unexported `.000` file or a dangling link, are named in the index reason
465
+ in `/status`.
466
+ - A saved index is rebuilt at start when a cell in the cells directory was added, removed or
467
+ given a new edition or update, with the cells named in the index reason. It was reused until
468
+ **Rebuild index at start** was ticked, so an added cell's rocks were missing from it.
469
+ - `M_SDAT` and `M_VDAT` datum areas are read. A cell with an area on another `VERDAT` than its
470
+ `DSID` datum is matched as an unknown datum (σ 0.5 m), listed with `datumAreas` in the
471
+ `/status` datum mapping. Only the `DSID` datum was read, so such a cell's water level could
472
+ be applied on the wrong datum.
473
+ - `scripts/enc-to-geojson.sh` exits non-zero when the source is unreadable, GDAL is missing or
474
+ cannot open the source, or the export has no `M_COVR`. Each of these ended in an empty or
475
+ unusable directory with exit status 0.
476
+ - Saving the index names its staging and backup directories by process, thread and a random
477
+ suffix. A WFS rebuild in the worker thread and a save on the main thread shared the process
478
+ id, so one save could delete the other's staging directory or its backup of the last index.
479
+ - The published package includes `scripts/enc-to-geojson.sh`, which the README and the
480
+ configuration tell users to run; it was left out of `files`.
481
+ - The `signalk-tide` source applies `heightNow` only for 5 minutes after the reading; after that
482
+ it takes the lower of `heightNow` and `heightLow` until 6 h past `environment.tide.timeLow`
483
+ (6 h past the reading without it), then falls back. It held `heightNow` for 30 minutes on a
484
+ falling tide and answered `heightLow` for any time past the next low water.
485
+ - A water-level fallback uses the source's last level when that is below chart datum, instead
486
+ of chart datum: in the Baltic the level is often negative, and a stale feed lowered P(UKC < 0).
487
+ - FMI is refetched once the held forecast is 25 minutes old, and retried each minute until a
488
+ fetch succeeds. With a 30-minute interval the level was a fallback for a few seconds every
489
+ 30 minutes, and one failed refetch made it a fallback for a whole interval.
490
+ - The lowest water level over a leg's ETA interval is also sampled at every FMI forecast point
491
+ inside it. Samples every 10 minutes from the start could miss a forecast trough by up to
492
+ half a sample step of its slope (−0.375 m for a −0.40 m trough at 30 cm/h).
493
+ - A Traficom WFS response or page body that sends nothing for 30 s fails the download with
494
+ that reason in `GET /status`, and the download is retried as after any failure. A stalled
495
+ server left the download busy for good, with no error. A slow link that keeps sending is read
496
+ to the end; a page over 64 MB fails the download.
497
+ - A WFS index build aborted by plugin stop no longer overlaps the next build: the next worker
498
+ starts only after the aborted one has exited. Stop still returns at once.
499
+ - The WFS build worker only stages its index; the main thread moves it into the index
500
+ directory, and never for an aborted build. A worker still exiting after stop could otherwise
501
+ replace the index the next start had just saved, or move it away while that start read it.
502
+ - After the plugin is stopped every REST route answers 503 `plugin not started`. Before,
503
+ `/query`, `/route-check`, `/route-repair`, `/departure-window` and the UKC tiles kept
504
+ answering on the old index at chart datum, so a rock could read `clear` and a route `ok`.
505
+ - The notification published when the plugin stops carries `data` with `engineState: "off"`
506
+ and null values, as `schemas/navigation-safety/notification.json` requires.
507
+ - Stopping the plugin publishes `navigation.underKeel.waterLevel` and `.envelopeRev` as `null`
508
+ as well; they kept their last values before.
509
+ - A mooring-zone load still running from an earlier start no longer writes its zones or
510
+ errors into the current start's status.
511
+ - A null or invalid navigation value from one `$source` clears the input only when that
512
+ source set it. With two GNSS receivers, one without a fix sending a null position every
513
+ second kept every tick `unknown` although the other had a good fix.
514
+ - A failed chart-index load stays shown as the plugin error in the server's plugin list; the
515
+ first look-ahead tick replaced it with an ordinary status line.
516
+ - Acknowledged passages are not honoured while the water level is a fallback, and `POST /acks`
517
+ answers 409 then. A stale tide feed fell back to 0 m, which compared as more water than an
518
+ acknowledgement made at −0.4 m and turned a warn into "acknowledged passage".
519
+ - `POST /acks` checks its polygon like `POST /query`: the ring must be closed, have no holes and
520
+ fit in 50 km without crossing ±180°. An unclosed ring lost a vertex, a hole was dropped so
521
+ the acknowledgement covered it, and a ring across ±180° became a band around the world.
522
+ - An acknowledgement that cannot be saved answers 500 `could not save acknowledgements` and is
523
+ logged to the server log. `DELETE /acks/:id` threw into express, which answered with an HTML
524
+ stack trace, and `POST /acks` answered 400 with the raw file-system error and its absolute
525
+ path. Other REST failures that are not a bad request body are a generic 500 as well.
526
+ - The envelope `rev` starts at the plugin's start time in ms instead of 0, so after a restart
527
+ `GET /envelope?rev=N` no longer answers 304 to a client holding a rev from the earlier run.
528
+ - UKC tiles are sent with `Cache-Control: no-cache`, as the Plotter Extensions spec asks for
529
+ tiles that change, so a browser revalidates them when the water level or draft changes.
530
+ - Holes in a mooring-zone region are kept: a footprint reaching into a hole, such as water cut
531
+ out around a rock, is outside the zone and its alarm is no longer demoted to alert. Only the
532
+ outer ring was read before.
533
+ - The living-chart quality gate drops a sounding whose position was measured more than 2 s
534
+ from the depth. Any fresh position counted before, up to 10 s old: about 30 m at 6 kn on
535
+ 76 m cells.
536
+ - Living-chart shoals survive a change of leaf zoom: saved adjustments are mapped onto the new
537
+ zoom instead of being dropped, which let the next save overwrite them. A `livechart.json`
538
+ that is unreadable, of another version or partly malformed is renamed to
539
+ `livechart.json.bad-<ms>` and reported instead of being overwritten at the next save.
540
+ - The grounding detector no longer treats a repeated, unchanged
541
+ `propulsion.*.transmission.gear` value as a gear change. Servers that publish the gear every
542
+ second vetoed every grounding.
543
+ - Hysteresis lowers a held `alarm` or `warn` once P inside that state's window (60 s, 120 s)
544
+ is clear. Risk further ahead held the state and its reason indefinitely, for example after
545
+ the vessel slowed.
546
+ - After `unknown` or `off`, a held risk state is lowered by the usual 5 clear ticks; before, the
547
+ first `normal` after the gap was published at once.
548
+ - The escape heading no longer recommends holding course when the vessel's own footprint is
549
+ already over shoal water. The footprint at the vessel is common to every heading and is not
550
+ scored; when no heading does better, `escapeHeading` is null.
551
+ - Heel no longer trusts one roll sample. A fin keel is lifted only by the least roll of the last
552
+ 10 s, and roll above 60° counts as no roll; before, a roll past 90° made a deeper draft
553
+ safer, and a boat rolling on alternate ticks never reached alarm.
554
+ - A `table` heel model without a fresh roll applies the table's largest draft change instead of
555
+ its smallest, and takes the largest change over the rolls seen; route checks, which have no
556
+ roll, use the largest change too.
557
+ - Look-ahead cost is bounded: the distance is capped at 5 NM and the minimum horizon at 600 s,
558
+ and a tick scores at most 400 footprints, spacing those beyond the warn window wider while
559
+ footprints still touch.
560
+ A 10 NM distance at 0.3 m/s took about 20 000 footprints and 10 s per 1 Hz tick.
561
+ - Squat uses the higher of SOG and STW, and is applied when COG is stale; before, it used SOG
562
+ only and was 0 whenever course or speed was stale.
563
+ - The look-ahead envelope draws water from an advisory (WFS) source, with unassessed survey
564
+ quality or against a fallback water level as `unverified`, never `clear`, as the README
565
+ states; before, those footprints were green while the state was `alert`.
566
+ - Route-check results reach the details panel on a chart host without data overlays, or while
567
+ the host is still loading the overlay style; the runtime stored them only after the overlay
568
+ call, which failed there. A visible route without a result reads "not checked yet" instead of
569
+ "No route on the chart."
570
+ - The runtime clears the stored route-check results when it starts. The host keeps extension
571
+ state across sessions, so the panel listed results from an earlier session as current.
572
+ - The status widget judges a value by its timestamp. Signal K replays its cached values on
573
+ every subscribe, so after a reconnect a normal state from a stalled plugin showed green for
574
+ up to 10 s. While stale, the widget shows no clearance or time to shoal under Unknown.
575
+ - The look-ahead overlay is withdrawn when the plugin goes quiet: after 10 s without an
576
+ `envelopeRev` delta, when the state is `off` or `unknown`, and when the envelope fetch fails.
577
+ Without a Signal K stream the runtime polls `/envelope` every 3 s; it fetched it once before.
578
+ - Route checks are re-run every 60 s and after a plugin restart, not only after a route edit,
579
+ so an ok leg no longer stays ok after the tide falls, the draft changes or the water-level
580
+ source falls back. The panel shows the age of each result and reads "out of date" past 3 min.
581
+ - The runtime refreshes the UKC tiles when the water level moves over 1 cm, the applied
582
+ water-level source or its degraded reason changes, the state enters or leaves `off` or
583
+ `unknown`, and after a plugin restart. Tiles stayed classed for the conditions at fetch time.
584
+ - The details panel shows Unknown when `/status` does not answer within 8 s or no answer has
585
+ arrived for 20 s. A request that hung left the chip on its last state, such as Normal.
586
+ - The details panel names the water-level source the engine applies and the reason it is
587
+ degraded, such as an FMI fallback, instead of the configured source.
588
+ - "Check routes again" is hidden on a chart host without `events.publish`, `routes` or
589
+ `background.iframe`, where pressing it did nothing.
590
+ - The background runtime writes route-check results to host state in a compact form (per leg
591
+ only index, status, minimum UKC and P), once per re-check of all routes instead of once per
592
+ route. Freeboard keeps that state in localStorage: one 30-leg route wrote 17.6 kB a minute
593
+ and three routes 158 kB; one route now writes 1.9 kB.
594
+ - A route check from the background runtime times out after 30 s and reads "not checked",
595
+ and a route is checked once at a time: a re-check asked for meanwhile runs after it. A hung
596
+ reply had no timeout, and each re-check opened another connection beside it.
597
+ - The runtime checks the visible routes one after another and, when the server answers 503
598
+ busy with `Retry-After`, checks again after it (at most five times). With six routes it
599
+ sent six checks at once, and those the server queue refused showed "busy" as the result.
600
+ - The details panel and the runtime poll `GET /status?summary`, which leaves out the cell
601
+ catalogue and datum mappings.
602
+ - The extension pages fetch nothing while Freeboard is in a hidden tab or minimised window.
603
+ On return the runtime withdraws the look-ahead envelope until a current one arrives and
604
+ asks for tile changes and route checks at once; the widget reads Unknown if its data aged
605
+ out meanwhile, even when its timer fired late. With the panel open they made 139 requests
606
+ in 65 s hidden.
607
+ - UKC tiles follow the wave allowance and the water level also without a Signal K stream: the
608
+ runtime asks the new `GET /tiles/ukc/changes` which tiles changed class, every 15 s and
609
+ after each 1 cm water-level move. A wave height change left tiles drawn for calmer water,
610
+ and without a stream the tiles never followed the tide. Freeboard now fetches only the tiles
611
+ whose classes changed: 2 tile fetches a minute instead of 108 with the tide rising 2 mm/s.
612
+ When that list does not answer, every tile is fetched again on a 1 cm fall or a 10 cm rise.
613
+ - A UKC tile beside a coarse index leaf, such as an unsplit z10 leaf next to a shoal, no longer
614
+ allocates a grid the size of that leaf. The tile route took about 300 MB and 150 ms per tile
615
+ at z18 and 4.3 GB at z20, and failed to allocate from z21. Its edge test now holds only the
616
+ slots within chart reach of the tile, at most 1024 slots past each edge: the z18 tile takes
617
+ 6 ms, and tiles are drawn as before.
618
+ - UKC tiles and `POST /query` take the water level valid where they are, not the vessel's. FMI's
619
+ forecast holds within 30 km of the point it was fetched for: a tile with every corner within
620
+ that reach is drawn at the forecast, and any other tile at the lower of the forecast and the
621
+ chart-datum fallback, marked degraded and with nothing `clear`. A query takes the same test
622
+ over its polygon's box widened by its buffer, so an area the reach cuts between two vertices,
623
+ or reaches only through the buffer, counts too, and beyond the reach it reports
624
+ `waterLevelDegraded` and is never `clear`. The degraded reason there, as on a route leg, says
625
+ the position is more than 30 km from where the forecast was fetched; it had said FMI held no
626
+ value for the time. A cursor readout off Vaasa took the surge forecast
627
+ for Kemi, +0.62 m, as measured, and wherever the index reached more than 30 km from the
628
+ forecast point the tiles there could read `clear` over water that may not be there. The tile
629
+ change list re-sends only the tiles that a new forecast point moves across the 30 km edge.
630
+ The look-ahead, notifications and `navigation.underKeel.waterLevel` keep the level at the
631
+ vessel.
632
+ - `GET /tiles/ukc/changes` lists the served tiles within chart reach of an index block that was
633
+ read in or dropped after the tile was drawn. A tile drawn from a block's coarse stand-ins
634
+ before the block loaded stayed on the plotter until the threshold left its range or the page
635
+ was reloaded. A small block a tile's own drawing reads on the spot no longer lists that tile
636
+ and its neighbours at the next poll, and the tile cache keeps that tile's cells instead of
637
+ walking it again at the next request.
638
+ - Position integrity no longer stays failed in a current. Starting underway in a stream, or
639
+ crossing into one, of about 0.6 m/s or more froze the current estimate: σ_pos grew to
640
+ kilometres within the hour, and the look-ahead was held at `warn` with no escape heading
641
+ although GNSS was right. The current is learned during a divergence too, and the warning
642
+ clears once it is learned, in about 2 minutes for 1 m/s. A position jump stays flagged as
643
+ before. A difference above 3 m/s (`maxCurrent`) is never taken as a current, and a failed run
644
+ clears only once both the low-passed and the latest difference are within that bound.
645
+ - A route leg whose ETA interval runs past the forecast, or whose far end lies beyond the
646
+ forecast's 30 km reach, no longer drops a lower forecast level. With FMI fetched at −0.10 m and forecasting −0.60 m,
647
+ such a leg was checked at −0.10 m. The leg is still degraded, `unverified` at best, but at the
648
+ lowest level found over its interval and ends.
649
+ - With no water-level source (`none`, the default), a chart whose sounding datum is not a
650
+ low-water datum gets a degraded level instead of chart datum taken as measured. This covers
651
+ the Finnish mean-water ENCs (VERDAT 3, 19 and 26), where the Baltic is often 0.3–0.8 m below
652
+ chart datum and a 1.8 m draft over a charted 2.6 m read `normal` and `ok`, as well as
653
+ high-water and local datums. On such charts the look-ahead is at best `alert`, route legs,
654
+ queries and tiles are at best `unverified`, and acknowledged passages and own soundings are
655
+ not used until a source is configured. The reason names the datums and the source to set, for
656
+ example "no water-level source, and chart datum is not low water (VERDAT 3, VERDAT 26); set
657
+ Water level source to fmi in Finnish waters, or to signalk-tide or manual"; `fmi` is named
658
+ only when one of those datums maps to an FMI series. Charts on low-water datums (LAT, MLLW and
659
+ the like) are unchanged. The setting is titled **Source** under **Water level**, and its
660
+ default stays `none`: no source is chosen automatically.
661
+ - A state held by hysteresis no longer republishes the escape heading of the tick that raised
662
+ it. That heading came from a position and course tens to hundreds of metres back and could
663
+ point at the shoal. A held tick publishes its own heading, null when the search found none,
664
+ was skipped or the tick itself reads `normal`.
665
+ - With a long look-ahead distance at low speed, the alarm and warn windows are scored at the
666
+ plan step again. With a 5 NM look-ahead at 0.3 m/s the footprints fell at 0 s and 77 s, so a
667
+ rock about 30 s ahead was reported as a warn 77 s ahead and never as an alarm, and at 1–2 kn
668
+ the time to shoal came 23–46 s late; the default 0.3 NM stretched the step to up to 5.4 s
669
+ between 0.5 and 0.9 kn. Only the spacing of the footprints beyond the warn window grows to fit
670
+ the 400-footprint budget.
671
+ - Escape headings are scored with the fan's spread, COG ± σ and rate of turn ± σ, as the state
672
+ is. Holding course was scored on one track, so when that track passed a shoal the COG + σ
673
+ track hit, the plotter offered "Dodge to" the course already steered during a `warn` or
674
+ `alarm`. When no heading does better than holding a steady course, `escapeHeading` is null; a
675
+ boat turning faster than the fan's rate-of-turn σ gets its current heading instead, since
676
+ stopping the turn is then the way out. The search now scores more headings where holding
677
+ course ended it at once: the look-ahead benchmark's p95
678
+ with the escape fan rose from about 46 ms to 74–105 ms under Jest, the median unchanged.
679
+ - Look-ahead footprints are placed from now, not from the position fix. A fix up to 10 s old
680
+ (`staleAfter`) is accepted, and every footprint, the time to shoal and the alarm and warn
681
+ windows lagged by SOG × its age: with a fix 5 s old at 8 m/s a rock under the bow read as
682
+ ahead. Escape turns start from now as well. The first footprint also covers the hull from the
683
+ fix to now: the age counts any skew between the GNSS clock and the server's, so the boat may
684
+ still be at the fix, and with a server clock 8 s ahead at 8 m/s a rock just ahead of the bow
685
+ was never scored.
686
+ - An acknowledged passage or mooring zone no longer turns into `alert` a `warn` or `alarm` on a
687
+ tick whose position uncertainty outgrew the 500 m buffer, whether the chart or the capped
688
+ buffer raised it, also when hysteresis holds a state with the chart's reason: an
689
+ acknowledgement covers an uncertain chart, not an untrusted position.
690
+ - Route repair no longer gives up on legs it can repair. On a 30 km leg the search cells are
691
+ 500 m, and a shoal a few hundred metres from a waypoint, outside its corridor, blocked the
692
+ end's cell and gave "no passable path in the search window"; the start and goal cells are now
693
+ scored at the leg's own ends with the corridor alone. Lines out of the start cell and into the
694
+ goal cell are checked as corridors from the waypoints themselves, over 1.5 cells: a rock
695
+ 150–400 m from a long leg's waypoint, inside its 500 m cell, made every repair fail with "the
696
+ path found does not pass the corridor check" although a small detour passed. Simplification
697
+ checks each chord at the time the boat reaches it: on a falling tide a chord could pass at the
698
+ leg's start time and fail at its own, and the repair was refused with the same reason. The
699
+ search grid takes the lowest water level until the boat could have sailed the grid's width
700
+ plus its height, not only over the straight leg's own times, so on a falling tide it no longer
701
+ plans over a bank that the final check, reading the detour's later pieces, finds too shallow.
702
+ - Route repair has a work limit per leg and per request, counted rather than timed, so a request
703
+ gives the same answer on any machine. The unit is a chart tile a depth query examines, plus 32
704
+ per query and one per 5 line-of-sight samples. A leg may do 600 000 units: its search stops at
705
+ 80 % of them and the leg gets no waypoints and the reason "the repair search reached the work
706
+ limit for one leg; add a waypoint near [lon, lat] (lon, lat) to split the leg, or use a
707
+ smaller xteLimit". The final check of the path counts too. Once a request's repairs have done
708
+ 1 800 000 units, later legs are listed as not searched. Nothing bounded a repair but its grid:
709
+ a 47 km leg at ±2 km over 135 000 near-threshold soundings took 2.2–3.4 s on a laptop, over
710
+ the 1.5 s Raspberry Pi 4 budget, while holding the single request slot. Repair grid cells are
711
+ now at least half the corridor half-width, so a 10 km leg at ±2 km no longer reads the same
712
+ water many times (2.5 s on a laptop with 167 m cells), and simplification no longer re-checks
713
+ the failing leg itself.
714
+ - Mooring zones suppress look-ahead warnings also when neither heading nor COG is fresh, as at a
715
+ berth, where every tick was published as `warn` or `alarm` with sound. Acknowledged passages
716
+ still need a heading.
717
+ - A mooring-zone region whose ring is not closed is reported and not loaded. Its last vertex was
718
+ dropped as if it repeated the first, which could enlarge the zone and demote warnings outside
719
+ it to `alert`.
720
+ - After a slow tick the next escape search is skipped and the heading cleared; after a slow
721
+ search the heading it found is kept and the next search waits the full 3 s. A search always
722
+ slower than 250 ms ran every 2 s, and later had its heading cleared a tick after finding it, so
723
+ the plotter showed the escape heading for 1 s in every 4; the plugin status now says the
724
+ searches are slow until a fast one runs. A slow search just before the danger passed no
725
+ longer holds back the first search when it returns.
726
+ - `notifications.navigation.positionIntegrity` is sent at once when its state or kind of reason
727
+ changes, and at most every 30 s while only its divergence or HDOP numbers drift. A lasting
728
+ warning went out again, with sound, about once a second.
729
+ - `POST /acks` answers 415 unless the `Content-Type` is `application/json` or another `+json`
730
+ type, and reads a `+json` body such as `application/geo+json` itself. Signal K parses only
731
+ `application/json` and leaves `{}` for any other body, so a form, a `text/plain` body, a
732
+ request without the header or `{polygon, ttl: 600}` sent as geo+json stored a default
733
+ acknowledgement over the current footprints with no expiry.
734
+ - `acks.json` keeps only unexpired acknowledgements: expired ones are dropped at the next add or
735
+ delete. `POST /acks` answers 409 once 100 unexpired acknowledgements exist, and refuses a
736
+ polygon of more than 64 vertices. Every `warn` and `alarm` tick tests the footprint against
737
+ each acknowledgement, and a client posting in a loop could grow the file and that cost without
738
+ end.
739
+ - Server file paths are kept out of what any client can read. `GET /status` no longer reports
740
+ `index.dir`, and its reasons (`index.reason`, `engine.reason`, `wfs.lastError`,
741
+ `chartBox.lastError`), the 5xx replies of the REST routes and UKC tiles, and every
742
+ notification message pass through one sanitizer: it shows a POSIX, Windows (`C:\`, `C:/`) or
743
+ UNC path as `<path>`, keeps URLs, numbers and an S-57 cell file's name (`<path>/US5MA22M.000`),
744
+ and turns the text after `failed:` into `failed (see the server log)`. A path holding a space
745
+ or an apostrophe (`/home/O'Reilly/…`), quoted or not, is hidden whole. With no index,
746
+ "UKC monitoring off: no cells in /srv/charts" went out on
747
+ `notifications.navigation.underKeel` as written, and the 503 of `/query` and the route
748
+ requests repeated the index reason, such as a `scandir` error naming the charts mount. Why a
749
+ saved index could not be read is still reported, with its paths hidden. The plugin status and
750
+ the server log keep the full text.
751
+ - An extension page request that the file system refuses, such as a name over 255 characters
752
+ (`ENAMETOOLONG`), a URL containing `%00`, or a page file that cannot be read, goes on to the
753
+ next handler like any unknown path. It reached Express's error handler, which answered 500
754
+ with a stack trace naming the install path outside production, on a route that needs no
755
+ login.
756
+ - Route-check legs from a result older than 3 minutes are drawn `unverified` on the chart, as
757
+ the panel's "out of date" badge says. After a tablet slept through a falling tide its legs
758
+ stayed green from the old water level, and while `route.list` failed they stayed green for
759
+ good. A route hidden while its check runs no longer comes back on the chart, and results for
760
+ routes the host no longer lists are dropped.
761
+ - The background runtime still starts the look-ahead overlay when a host state write, such as
762
+ one over the storage quota, or a subscription fails at load; such a failure ended it for the
763
+ session. A failed Signal K stream subscription falls back to polling `/envelope` every 3 s.
764
+ - On an index read block by block, the living chart reads a cell's chart prior only from a
765
+ loaded block. Priors read at start, at each rebind and at a cell's first sounding came from
766
+ the blocks' stand-ins, metres too shallow or uncharted, which hid or missed discrepancies: a
767
+ cell charted 18.2 m was rebased onto 5.4 m, and 12 m soundings there raised nothing. A cell
768
+ whose block is not loaded is settled in the background once the block loads and is judged
769
+ again; `GET /status` counts such cells as `livechart.unsettled`. Restored cells compute no
770
+ chart prior during plugin start: saved adjustments apply at once, and every cell waits for the
771
+ settler, which judges it against the current chart in slices of 1 000 from the next turn of
772
+ the event loop. A long history blocked a Raspberry Pi 4 for seconds at start.
773
+ - `GET /livechart/discrepancies` returns `charted: null`, and the note reads "(not charted)",
774
+ for a discrepancy cell the index in use gives no depth. The note read "charted NaN m". A cell
775
+ whose chart block is not read yet is marked `pending: true` instead, and its note waits until
776
+ the chart is read: a note written by a stop or a save in that state read "(not charted)" and
777
+ stayed so. After a start each note is rewritten once its cell has been judged against the
778
+ current chart.
779
+ - Until a living-chart cell is judged against the chart after a start or an index swap, its
780
+ adjustment names no ENC cell. It carried the old catalogue's cell number, so `/query` results
781
+ and explanation terms could name the wrong cell, edition and update.
782
+ - A rewrite of `soundings.ndjson` with no soundings, as after a log of only malformed lines was
783
+ set aside, wrote a lone newline. At the next start it read back as a malformed line, and the
784
+ log was set aside again.
785
+ - Soundings in a `livechart.json` from an older version stay in it until `soundings.ndjson`
786
+ holds them. A failed log write followed by a state save lost them.
787
+ - A cell's file stamp covers the updates GDAL applies and is taken just before GDAL reads the
788
+ cell. For a linked `.000` the updates beside the link's target and named after it were left
789
+ out, so a saved index stayed in use without an update installed there, and an update added
790
+ during a build was recorded as applied although it had not been read.
791
+ - The Traficom WFS cell is flushed to disk before it replaces the previous one, and the previous
792
+ cell is kept when the swap fails. A power cut just after a refresh could leave an empty layer
793
+ file, and a failed rename left no cell at all.
794
+ - After a power cut between the two renames of an index save, the box index the start recovers
795
+ is no longer rebuilt at the berth right after it is handed over: the box service looked for
796
+ the saved box before the start had moved the index back.