signalk-chiplog 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ All notable changes to Chiplog are documented here. The format follows
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-09-18
+
+### Added
+
+- **Import a PostgSail logbook.** `node scripts/import-postgsail.js <trips.geojson> --url <server>` reads PostgSail's
+  GeoJSON export and adds each trip as a passage — track, wind, engine and sail periods, place names, fuel level, house
+  battery, instrument snapshots — through the API, so the logbook can be on the boat's server. It is safe to run again:
+  a passage already on record is skipped. The route it uses, `POST /entries` (administrator), adds any finished passage
+  and answers `409 entry_overlaps` when it overlaps one on record. See the README's _Importing from PostgSail_.
+
+## [2.4.0] - 2026-09-18
+
+### Added
+
+- **Previous and next passage links at the top of a passage page**, to step through the log without going back to it.
+  `GET /entries/:id` gives them as `previousEntryId` and `nextEntryId`, in the log's order. Alt+← and Alt+→ do the same
+  from the keyboard.
+- **A Statistics page** sums the logbook up over a period: number of passages, first and last dates, total distance,
+  time under way, top speed, strongest wind, the longest passage without a stop (a passage is cut at its stopovers, each
+  stretch measured on its own), the flags of the countries visited, and the top 5 passages by duration, distance,
+  average speed, top speed and wind. The period is a shortcut — all time, this month, last month, the last 12 months,
+  this year, last year — or a range picked in a calendar with two clicks, the first and the last day. It reads
+  `GET /statistics`.
+- **One range picker for every date range** in the webapp: the Animation, Export and Retrospective pages use the same
+  calendar — two clicks, the first and the last day — instead of a pair of date fields, so a range with its end before
+  its start can no longer be entered.
+- **Places now know their country** (`countryCode` on `GET /places`), from the same geocoding lookup that names them;
+  places saved earlier, or added by hand, are asked about in the background once pending names are done. Database
+  migration 16.
+
 ## [2.3.1] - 2026-09-18
 
 ### Added
@@ -287,7 +317,9 @@ First release.
 - REST API under `/plugins/signalk-chiplog/api`, documented in [docs/API.md](docs/API.md).
 - Single SQLite database through Node's built-in `node:sqlite`: no native module to build.
 
-[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.1...HEAD
+[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.1...v2.4.0
 [2.3.1]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.1.0...v2.2.0

package/README.md

@@ -30,6 +30,7 @@ English and French, chosen from the browser's language.
 - [Signal K data used](#signal-k-data-used-)
 - [Backups and abandon ship](#backups-and-abandon-ship-)
 - [Retrospective analysis](#retrospective-analysis-)
+- [Importing from PostgSail](#importing-from-postgsail-)
 - [Privacy and online services](#privacy-and-online-services-)
 - [Troubleshooting](#troubleshooting-)
 - [Limitations](#limitations-)
@@ -201,36 +202,48 @@ Open **Chiplog** from the Signal K webapps, or `/signalk-chiplog/`. Reading need
   not just what is loaded), then passages grouped by day, newest first, with times, departure and arrival, distance,
   duration and an engine/sail bar. A passage across midnight appears on both days. Provisional place names are shown as
   such.
-- **Passage page** — summary (distance, duration, average speed, the highest speed and wind seen, and the crew aboard),
-  map of the track (OpenStreetMap with OpenSeaMap seamarks, which can be hidden) with a small boat marker at the
-  selected point, a scrubber under the map to step back and forth through its history (defaulting to the latest point,
-  so it shows the current position on a passage in progress) with a band of that point's time, SOG, COG, STW, TWS, TWD,
-  TWA and AWA, the marine weather forecast every 3 hours from departure, the tide forecast near the departure (place,
-  high/low times and heights, height curve) when one was fetched, the engine and sail periods, the boat's status (each
-  engine's hour counter at departure and arrival and the hours run, and the tank levels and battery charge, voltage and
-  current noted at departure), and the log: every reading and event in order, including handwritten notes. A passage in
-  progress refreshes every minute. Each line's comment can be edited (read/write access); a manoeuvre or note the crew
-  logged themselves can also be deleted — automatic lines (alarms, autopilot, weather, corrections) can only be
-  annotated. Under each position, in grey, its bearing and distance from the nearest landmark.
+- **Passage page** — links at the top to the previous and the next passage (or **Alt+←** and **Alt+→**), then a summary
+  (distance, duration, average speed, the highest speed and wind seen, and the crew aboard), map of the track
+  (OpenStreetMap with OpenSeaMap seamarks, which can be hidden) with a small boat marker at the selected point, a
+  scrubber under the map to step back and forth through its history (defaulting to the latest point, so it shows the
+  current position on a passage in progress) with a band of that point's time, SOG, COG, STW, TWS, TWD, TWA and AWA, the
+  marine weather forecast every 3 hours from departure, the tide forecast near the departure (place, high/low times and
+  heights, height curve) when one was fetched, the engine and sail periods, the boat's status (each engine's hour
+  counter at departure and arrival and the hours run, and the tank levels and battery charge, voltage and current noted
+  at departure), and the log: every reading and event in order, including handwritten notes. A passage in progress
+  refreshes every minute. Each line's comment can be edited (read/write access); a manoeuvre or note the crew logged
+  themselves can also be deleted — automatic lines (alarms, autopilot, weather, corrections) can only be annotated.
+  Under each position, in grey, its bearing and distance from the nearest landmark.
 - **Corrections** (read/write access):
   - rename the departure, or the arrival once the passage is closed — a passage in progress has none yet to rename;
   - switch an engine period to sail or back;
   - close a passage in progress, e.g. to confirm an arrival;
   - merge with the previous or next passage;
   - delete a passage (admin).
-- **Animation** — pick two dates and every passage between them replays on the map, one after another, the port time
-  skipped. The map follows the boat at a scale chosen for each passage — a short hop kept readable rather than
-  magnified, a long crossing allowed a wider view but never so wide the boat crawls across empty water — while a bubble
-  shows the speed, the distance covered since the start and the date. Play, pause and a slider over the animation's own
-  time, at ×0,5, ×1, ×2 or ×4. **Export MP4** saves it as a video in one of five shapes (Mobile 9:16, Portrait 3:4,
-  Square 1:1, Landscape 4:3, Widescreen 16:9). Everything happens in the browser: nothing is rendered or encoded on the
-  Signal K server, and the map tiles are the only thing downloaded.
+- **Statistics** — the logbook summed up over a period: a shortcut (all time, this month, last month, the last 12
+  months, this year, last year) or a range picked in a calendar with two clicks, the first and the last day. It gives
+  the number of passages, the dates of the first and the last, total distance, time under way, top speed and strongest
+  wind, the longest passage without a stop (a passage with a stopover counts as its stretches between stops) with its
+  distance and time, the flags of the countries visited, and the top 5 passages by duration, distance, average speed,
+  top speed and wind. Countries come from the place names, so they need geocoding enabled and the boat online now and
+  then; places named before this existed fill in by themselves.
+- **Animation** — pick a period and every passage in it replays on the map, one after another, the port time skipped.
+  The map follows the boat at a scale chosen for each passage — a short hop kept readable rather than magnified, a long
+  crossing allowed a wider view but never so wide the boat crawls across empty water — while a bubble shows the speed,
+  the distance covered since the start and the date. Play, pause and a slider over the animation's own time, at ×0,5,
+  ×1, ×2 or ×4. **Export MP4** saves it as a video in one of five shapes (Mobile 9:16, Portrait 3:4, Square 1:1,
+  Landscape 4:3, Widescreen 16:9). Everything happens in the browser: nothing is rendered or encoded on the Signal K
+  server, and the map tiles are the only thing downloaded.
 - **Export** — download the whole logbook or a date range as a PDF logbook to print, JSON, CSV or GPX, and write the
   abandon-ship copy to the USB drive now (admin). The PDF is written in the webapp's language and the device's time
   zone.
 - **Retrospective** (admin) — reconstruct past passages for a date range from an InfluxDB history (see
   [Retrospective analysis](#retrospective-analysis-)).
 
+Every date range in the webapp — Statistics, Animation, Export and Retrospective — is picked the same way: one button
+showing the period, and a calendar under it where two clicks, the first and the last day, make the range. Statistics has
+shortcuts beside it; where any date is allowed, the calendar has an _Any date_ button to clear the range.
+
 **Helm entry** in the top bar opens the tablet entry app.
 
 ## The tablet entry app 📱
@@ -405,11 +418,39 @@ at the time.
   track has one point per **Track point interval**. Everything else read from a continuously published path — position,
   speed, wind, engine, autopilot, depth, barometer — is reconstructed the same as live.
 
+## Importing from PostgSail 📥
+
+Kept your logbook with [PostgSail](https://github.com/xbgmsharp/postgsail) until now? Its GeoJSON export — one trip or
+several — comes into Chiplog with the script `scripts/import-postgsail.js`, run from a checkout of this repository (Node
+22.13 or later, nothing to install). It talks to the plugin's REST API, so the logbook can be on the boat's Signal K
+server while you run it from your own computer.
+
+```bash
+node scripts/import-postgsail.js PostgSail_Trip.geojson --url http://boat.local:3000 --token <token>
+```
+
+- **Administrator access.** Give the token of an administrator with `--token` (or `CHIPLOG_TOKEN`), or sign in with
+  `--user` and `--password` (or `CHIPLOG_PASSWORD`); a server without Signal K security needs neither.
+- **Each trip becomes a passage**, with its track, wind and speed, the engine and sail periods read from PostgSail's
+  _sailing_ and _motoring_ status, the places from the trip name, and instrument snapshots every hour on the clock
+  (`--observation-interval <minutes>`, `0` for none).
+- **Safe to run again.** A passage that overlaps one already in the logbook is skipped, so a run cut short is finished
+  by running the same command; nothing is duplicated. `--dry-run` lists what the file holds without sending anything.
+- **Boat state at departure.** PostgSail's tank level is taken as the fuel tank, and its voltage and state of charge as
+  the house battery, noted like Chiplog does live.
+- **Not imported:** PostgSail's own distance — Chiplog sums the track, as for every passage, which lands within a few
+  percent of it.
+- Place names come as PostgSail has them. Passages near a place Chiplog already knows are named the same; the countries
+  and landmarks are then looked up in the background, like for any passage. Tide and weather forecasts are not fetched
+  for passages this old.
+
 ## Privacy and online services 🔒
 
 - **Place names.** With geocoding on, the position of each departure and arrival that matches no known place is sent to
   the geocoding service — OpenStreetMap's public Nominatim by default. Nothing else is sent, and nothing at all when it
   is off.
+- **Countries.** With geocoding on, a place whose country is not known yet has its position sent to the geocoding
+  service once, to ask which country it is in. Nothing at all when it is off.
 - **Landmarks.** With them on, the area a passage sailed through — a half-degree box, not its track — is sent to the
   Overpass service, OpenStreetMap's public instance by default, once per area ever. Nothing at all when it is off.
 - **Tide forecast.** With it on, the departure position of each passage is sent to the tide service — the public
@@ -535,6 +576,7 @@ npm install          # also copies the browser libraries into public/vendor/
 npm test
 npm run lint
 npm run demo:seed -- /tmp/chiplog-demo   # a demo logbook to try the webapps with
+npm run import:postgsail -- <trips.geojson> --url <server>   # see Importing from PostgSail
 ```
 
 The functional specification is in [docs/SPEC.md](docs/SPEC.md), the data model in

package/lib/api.js

@@ -8,10 +8,12 @@ const { listEntryLandmarks } = require('./landmarks');
 const { isTimeZone, PDF_LANGUAGES } = require('./logbook-pdf');
 const { toGeoJson, toGpx } = require('./formats');
 const manoeuvreTypes = require('./manoeuvre-types');
+const { importPassage, TRACK_READINGS, OBSERVATION_READINGS } = require('./passage-import');
 const places = require('./places');
 const propulsion = require('./propulsion');
 const { getTideForecast } = require('./tide-forecaster');
 const { getWeatherForecast } = require('./weather-forecaster');
+const { getStatistics } = require('./statistics');
 const track = require('./track');
 const v = require('./validation');
 
@@ -80,6 +82,112 @@ function parseRange(query) {
   };
 }
 
+const TRACK_POINT_FIELDS = ['time', 'lat', 'lon', ...TRACK_READINGS];
+const OBSERVATION_FIELD_READINGS = OBSERVATION_READINGS.map(([, field]) => field);
+const OBSERVATION_FIELDS = ['time', 'reason', 'position', ...OBSERVATION_FIELD_READINGS];
+const OBSERVATION_REASONS = ['periodic', 'entry_start', 'entry_end', 'event'];
+
+const nullableNumber = (value, name) => (value === null ? null : v.parseNumber(value, name));
+
+// A list of objects in a request body, each checked field by field; an absent
+// list is an empty one.
+function parseList(body, field, parseItem) {
+  if (!(field in body)) {
+    return [];
+  }
+  if (!Array.isArray(body[field])) {
+    throw badRequest(`${field} must be an array`);
+  }
+  return body[field].map((item, index) => parseItem(item, `${field}[${index}]`));
+}
+
+function parseTrackPoint(item, name) {
+  const point = v.requireBody(item, TRACK_POINT_FIELDS);
+  const { lat, lon } = v.parsePosition({ lat: point.lat, lon: point.lon }, name);
+  return {
+    time: v.parseTimestamp(point.time, `${name}.time`),
+    lat,
+    lon,
+    ...Object.fromEntries(
+      TRACK_READINGS.filter((reading) => reading in point).map((reading) => [
+        reading,
+        nullableNumber(point[reading], `${name}.${reading}`)
+      ])
+    )
+  };
+}
+
+function parseObservation(item, name) {
+  const observation = v.requireBody(item, OBSERVATION_FIELDS);
+  return {
+    time: v.parseTimestamp(observation.time, `${name}.time`),
+    reason: v.parseEnum(observation.reason, `${name}.reason`, OBSERVATION_REASONS),
+    position: optional(observation, 'position', v.parsePosition),
+    ...Object.fromEntries(
+      OBSERVATION_FIELD_READINGS.filter((reading) => reading in observation).map((reading) => [
+        reading,
+        nullableNumber(observation[reading], `${name}.${reading}`)
+      ])
+    )
+  };
+}
+
+// A tank as noted at departure: level as a ratio, volume and capacity in m³.
+function parseTank(item, name) {
+  const tank = v.requireBody(item, ['type', 'id', 'name', 'level', 'volume', 'capacity']);
+  const readings = ['level', 'volume', 'capacity'].filter((field) => tank[field] != null);
+  if (!('level' in tank || 'volume' in tank)) {
+    throw badRequest(`${name} needs a level or a volume`);
+  }
+  return {
+    type: v.parseString(tank.type, `${name}.type`, { maxLength: 40 }),
+    id: v.parseString(tank.id, `${name}.id`, { maxLength: 40 }),
+    ...(tank.name == null
+      ? {}
+      : { name: v.parseString(tank.name, `${name}.name`, { maxLength: 100 }) }),
+    ...Object.fromEntries(
+      readings.map((field) => [field, v.parseNonNegativeNumber(tank[field], `${name}.${field}`)])
+    )
+  };
+}
+
+// A battery as noted at departure: volts, amps (negative discharging), state of
+// charge as a ratio, kelvin.
+function parseBattery(item, name) {
+  const battery = v.requireBody(item, [
+    'id',
+    'name',
+    'voltage',
+    'current',
+    'stateOfCharge',
+    'temperature'
+  ]);
+  const readings = ['voltage', 'current', 'stateOfCharge', 'temperature'].filter(
+    (field) => battery[field] != null
+  );
+  if (readings.length === 0) {
+    throw badRequest(`${name} needs at least one reading`);
+  }
+  return {
+    id: v.parseString(battery.id, `${name}.id`, { maxLength: 40 }),
+    ...(battery.name == null
+      ? {}
+      : { name: v.parseString(battery.name, `${name}.name`, { maxLength: 100 }) }),
+    ...Object.fromEntries(
+      readings.map((field) => [field, v.parseNumber(battery[field], `${name}.${field}`)])
+    )
+  };
+}
+
+function parsePropulsionPeriod(item, name) {
+  const segment = v.requireBody(item, ['type', 'startTime', 'endTime']);
+  return {
+    type: v.parseEnum(segment.type, `${name}.type`, ['engine', 'sail']),
+    startTime: v.parseTimestamp(segment.startTime, `${name}.startTime`),
+    endTime: v.parseTimestamp(segment.endTime, `${name}.endTime`)
+  };
+}
+
 function registerRoutes(router, { getContext, logError }) {
   const readonly = scoped(router, 'readonly');
   const readwrite = scoped(router, 'readwrite');
@@ -132,11 +240,57 @@ function registerRoutes(router, { getContext, logError }) {
     handle(({ db, now }, req) => entries.getStats(db, { ...parseRange(req.query), now: now() }))
   );
 
+  readonly.get(
+    '/api/statistics',
+    handle(({ db, now }, req) => getStatistics(db, { ...parseRange(req.query), now: now() }))
+  );
+
   readonly.get(
     '/api/entries/:id',
     handle(({ db }, req) => entries.getEntry(db, entryId(req)))
   );
 
+  // A finished passage recorded elsewhere, such as another logbook's export.
+  admin.post(
+    '/api/entries',
+    handle(({ db, config, now }, req, res) => {
+      const body = v.requireBody(req.body, [
+        'startTime',
+        'endTime',
+        'startPosition',
+        'endPosition',
+        'startPlaceName',
+        'endPlaceName',
+        'distance',
+        'startTanks',
+        'startBatteries',
+        'trackPoints',
+        'observations',
+        'propulsion'
+      ]);
+      const entry = importPassage(
+        db,
+        {
+          startTime: v.parseTimestamp(body.startTime, 'startTime'),
+          endTime: v.parseTimestamp(body.endTime, 'endTime'),
+          startPosition: optional(body, 'startPosition', v.parsePosition) ?? null,
+          endPosition: optional(body, 'endPosition', v.parsePosition) ?? null,
+          startPlaceName: optional(body, 'startPlaceName', nullableString(200)) ?? null,
+          endPlaceName: optional(body, 'endPlaceName', nullableString(200)) ?? null,
+          distance: optional(body, 'distance', v.parseNonNegativeNumber),
+          startTanks: parseList(body, 'startTanks', parseTank),
+          startBatteries: parseList(body, 'startBatteries', parseBattery),
+          trackPoints: parseList(body, 'trackPoints', parseTrackPoint),
+          observations: parseList(body, 'observations', parseObservation),
+          propulsion: parseList(body, 'propulsion', parsePropulsionPeriod)
+        },
+        { placeMatchRadius: config.placeMatchRadius, now: now() }
+      );
+      res.status(201);
+      return entry;
+    })
+  );
+
   readwrite.patch(
     '/api/entries/:id',
     handle(({ db, config, now }, req) => {

package/lib/database.js

@@ -358,6 +358,19 @@ const MIGRATIONS = [
   -- passages default to pending, so their areas are fetched too.
   ALTER TABLE log_entries ADD COLUMN landmarks_pending INTEGER NOT NULL DEFAULT 1
     CHECK (landmarks_pending IN (0, 1));
+  `,
+  `
+  -- The country a place is in (SPEC §4.14), as an upper-case ISO 3166-1
+  -- alpha-2 code, for the statistics page's visited countries. It lives on the
+  -- place rather than on each entry: a passage reaches its country through
+  -- start_place_id / end_place_id. country_checked says the lookup has been
+  -- made, so a place whose position has no country (open water, or geocoding
+  -- switched off after the fact) is not asked about forever. Existing places
+  -- start unchecked and are filled in by the same background chain that names
+  -- pending departures.
+  ALTER TABLE places ADD COLUMN country_code TEXT;
+  ALTER TABLE places ADD COLUMN country_checked INTEGER NOT NULL DEFAULT 0
+    CHECK (country_checked IN (0, 1));
   `
 ];
 

package/lib/entries.js

@@ -48,7 +48,7 @@ function requireEntryRow(db, id) {
   return row;
 }
 
-// Shared by listEntries and getStats, so a date range means the same thing
+// Shared by listEntries, getStats and the statistics page, so a date range means the same thing
 // to both: matched on startTime, from inclusive and to exclusive.
 function rangeWhere({ from, to }) {
   const conditions = [];
@@ -94,8 +94,27 @@ function getStats(db, { from, to, now }) {
   return { count: row.count, distance: row.distance, duration: Math.round(row.duration) };
 }
 
+// The passages either side of this one in the log's order (start time, then
+// id), for a page to step to its neighbours.
+function neighbourIds(db, row) {
+  const before = db
+    .prepare(
+      `SELECT id FROM log_entries WHERE start_time < ?1 OR (start_time = ?1 AND id < ?2)
+       ORDER BY start_time DESC, id DESC LIMIT 1`
+    )
+    .get(row.start_time, row.id);
+  const after = db
+    .prepare(
+      `SELECT id FROM log_entries WHERE start_time > ?1 OR (start_time = ?1 AND id > ?2)
+       ORDER BY start_time, id LIMIT 1`
+    )
+    .get(row.start_time, row.id);
+  return { previousEntryId: before?.id ?? null, nextEntryId: after?.id ?? null };
+}
+
 function getEntry(db, id) {
-  const entry = toEntry(requireEntryRow(db, id));
+  const row = requireEntryRow(db, id);
+  const entry = toEntry(row);
   const count = (table) =>
     db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE entry_id = ?`).get(id).n;
   const maxSpeed = db
@@ -116,6 +135,7 @@ function getEntry(db, id) {
     .get(id, id);
   return {
     ...entry,
+    ...neighbourIds(db, row),
     counts: {
       trackPoints: count('track_points'),
       observations: count('observations'),
@@ -488,6 +508,7 @@ function deleteEntry(db, id) {
 module.exports = {
   toEntry,
   requireEntryRow,
+  rangeWhere,
   listEntries,
   getStats,
   getEntry,

package/lib/passage-import.js

@@ -0,0 +1,190 @@
+const { withTransaction } = require('./database');
+const { badRequest, conflict } = require('./errors');
+const { getEntry, recomputeDurations } = require('./entries');
+const { initialPlaceName } = require('./place-names');
+const { distanceBetween, findNearestPlace } = require('./places');
+
+const TRACK_READINGS = ['sog', 'cog', 'stw', 'heading', 'tws', 'twd', 'aws', 'awa'];
+// [column, request field]
+const OBSERVATION_READINGS = [
+  ...TRACK_READINGS.map((reading) => [reading, reading]),
+  ['depth', 'depth'],
+  ['pressure', 'pressure'],
+  ['air_temp', 'airTemp'],
+  ['water_temp', 'waterTemp'],
+  ['trip_log', 'tripLog'],
+  ['engine_runtime', 'engineRuntime']
+];
+
+// An anchorage is not left at the same spot twice: a place of the same name this close
+// is the same place, though further than the matching radius.
+const SAME_NAME_REACH_METRES = 500;
+
+// A passage recorded elsewhere is only ever added next to the ones on record,
+// never on top of them: the vessel was in one place at a time, so an overlap
+// means the passage is already there, or that one of the two is wrong.
+function requireNoOverlap(db, startTime, endTime) {
+  const clash = db
+    .prepare(
+      `SELECT id FROM log_entries
+       WHERE start_time < ? AND COALESCE(end_time, '9999-12-31T23:59:59.999Z') > ?
+       ORDER BY start_time LIMIT 1`
+    )
+    .get(endTime, startTime);
+  if (clash) {
+    throw conflict('entry_overlaps', `The passage overlaps entry ${clash.id} already on record`);
+  }
+}
+
+// The name comes from the source, so it is kept as given; the position is tied
+// to a known place when there is one in reach, or made into one, so a later
+// departure from the same spot is named the same way. Without a name it is
+// named as a passage detected live would be.
+function resolvePlace(db, position, name, radius, now) {
+  if (!position) {
+    return { id: null, name: name ?? null, pending: 0 };
+  }
+  if (name === null || name === undefined) {
+    return initialPlaceName(db, position, radius);
+  }
+  const known =
+    findNearestPlace(db, position, radius) ??
+    db
+      .prepare('SELECT * FROM places WHERE name = ? COLLATE NOCASE')
+      .all(name)
+      .find((place) => distanceBetween(position, place) <= SAME_NAME_REACH_METRES);
+  if (known) {
+    return { id: known.id, name, pending: 0 };
+  }
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO places (name, lat, lon, source, created_at, updated_at)
+       VALUES (?, ?, ?, 'manual', ?, ?)`
+    )
+    .run(name, position.lat, position.lon, now, now);
+  return { id: Number(lastInsertRowid), name, pending: 0 };
+}
+
+function requireWithin(startTime, endTime, time, name) {
+  if (time < startTime || time > endTime) {
+    throw badRequest(`${name} must fall between startTime and endTime`);
+  }
+}
+
+function trackDistance(points) {
+  let total = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    total += distanceBetween(points[i - 1], points[i]);
+  }
+  return total;
+}
+
+// Adds a finished passage recorded elsewhere -- another logbook's export --
+// with its track, instrument readings and engine/sail periods. All or nothing.
+// Unlike anything detection writes, its `closed_by` stays empty, so a departure
+// soon after it never reopens it. Without a `distance`, the passage's is the
+// sum over its track, as it is for one logged live.
+function importPassage(db, input, { placeMatchRadius, now }) {
+  const { startTime, endTime } = input;
+  if (endTime < startTime) {
+    throw badRequest('endTime must not be earlier than startTime');
+  }
+  input.trackPoints.forEach((point, index) =>
+    requireWithin(startTime, endTime, point.time, `trackPoints[${index}].time`)
+  );
+  input.observations.forEach((observation, index) =>
+    requireWithin(startTime, endTime, observation.time, `observations[${index}].time`)
+  );
+  input.propulsion.forEach((segment, index) => {
+    requireWithin(startTime, endTime, segment.startTime, `propulsion[${index}].startTime`);
+    requireWithin(startTime, endTime, segment.endTime, `propulsion[${index}].endTime`);
+    if (segment.endTime < segment.startTime) {
+      throw badRequest(`propulsion[${index}].endTime must not be earlier than its startTime`);
+    }
+  });
+
+  return withTransaction(db, () => {
+    requireNoOverlap(db, startTime, endTime);
+
+    const start = resolvePlace(
+      db,
+      input.startPosition,
+      input.startPlaceName,
+      placeMatchRadius,
+      now
+    );
+    const end = resolvePlace(db, input.endPosition, input.endPlaceName, placeMatchRadius, now);
+    const { lastInsertRowid } = db
+      .prepare(
+        `INSERT INTO log_entries (
+           state, start_time, end_time, start_lat, start_lon, end_lat, end_lon,
+           start_place_id, end_place_id, start_place_name, end_place_name,
+           start_place_pending, end_place_pending, distance, start_tanks, start_batteries, created_at,
+           updated_at
+         ) VALUES ('closed', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(
+        startTime,
+        endTime,
+        input.startPosition?.lat ?? null,
+        input.startPosition?.lon ?? null,
+        input.endPosition?.lat ?? null,
+        input.endPosition?.lon ?? null,
+        start.id,
+        end.id,
+        start.name,
+        end.name,
+        start.pending,
+        end.pending,
+        input.distance ?? trackDistance(input.trackPoints),
+        input.startTanks.length > 0 ? JSON.stringify(input.startTanks) : null,
+        input.startBatteries.length > 0 ? JSON.stringify(input.startBatteries) : null,
+        now,
+        now
+      );
+    const entryId = Number(lastInsertRowid);
+
+    const insertPoint = db.prepare(
+      `INSERT INTO track_points (entry_id, time, lat, lon, ${TRACK_READINGS.join(', ')})
+       VALUES (?, ?, ?, ?, ${TRACK_READINGS.map(() => '?').join(', ')})`
+    );
+    for (const point of input.trackPoints) {
+      insertPoint.run(
+        entryId,
+        point.time,
+        point.lat,
+        point.lon,
+        ...TRACK_READINGS.map((reading) => point[reading] ?? null)
+      );
+    }
+
+    const insertObservation = db.prepare(
+      `INSERT INTO observations (
+         entry_id, time, reason, lat, lon, ${OBSERVATION_READINGS.map(([column]) => column).join(', ')}
+       ) VALUES (?, ?, ?, ?, ?, ${OBSERVATION_READINGS.map(() => '?').join(', ')})`
+    );
+    for (const observation of input.observations) {
+      insertObservation.run(
+        entryId,
+        observation.time,
+        observation.reason,
+        observation.position?.lat ?? null,
+        observation.position?.lon ?? null,
+        ...OBSERVATION_READINGS.map(([, field]) => observation[field] ?? null)
+      );
+    }
+
+    const insertSegment = db.prepare(
+      `INSERT INTO propulsion_segments (entry_id, type, start_time, end_time, source)
+       VALUES (?, ?, ?, ?, 'auto')`
+    );
+    for (const segment of input.propulsion) {
+      insertSegment.run(entryId, segment.type, segment.startTime, segment.endTime);
+    }
+    recomputeDurations(db, entryId, now);
+
+    return getEntry(db, entryId);
+  });
+}
+
+module.exports = { importPassage, TRACK_READINGS, OBSERVATION_READINGS };