first commit

docs/geospatial/logistics/ports/src/lane-distance/lane-distance.md

@@ -0,0 +1,65 @@
+# lane-distance
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Computes great-circle distance metrics for a `ShippingLane`'s waypoint
+chain. `estimateLaneDistance` sums every segment for the lane total;
+`cumulativeDistances` returns the per-waypoint cumulative array used by
+`findPositionOnLane` and `estimateETA`. Both functions reject lanes
+with fewer than two waypoints because any distance metric over a
+single-point chain is undefined.
+
+## Features
+
+- `estimateLaneDistance(lane)` — total nautical miles, rounded to two
+  decimals.
+- `cumulativeDistances(lane)` — `number[]` of length `waypoints.length`
+  where entry 0 is 0 and entry i is the cumulative nm distance from
+  `waypoints[0]` to `waypoints[i]`.
+- Throws `PortsInsufficientWaypointsError`
+  (`PORTS.INSUFFICIENT_WAYPOINTS`) for lanes shorter than two
+  waypoints.
+- Emits the `ports.lane_distance_duration_ms` histogram.
+- Uses the package's shared `distanceNm` helper so the rounding policy
+  is centralised.
+
+## Usage: Basic
+
+```ts
+import { estimateLaneDistance, getShippingLaneStrict } from "@suaveplan/ports";
+
+const suez = getShippingLaneStrict("asia-europe-suez");
+const totalNm = estimateLaneDistance(suez);
+```
+
+## Usage: Advanced
+
+```ts
+import { cumulativeDistances, getShippingLaneStrict } from "@suaveplan/ports";
+
+const lane = getShippingLaneStrict("asia-europe-suez");
+const cum = cumulativeDistances(lane);
+// cum[i] - cum[i-1] gives segment length between waypoints i-1 and i.
+for (let i = 1; i < cum.length; i++) {
+    console.log("segment", i, cum[i] - cum[i - 1], "nm");
+}
+```
+
+## API Reference
+
+- `estimateLaneDistance(lane: ShippingLane): number`.
+- `cumulativeDistances(lane: ShippingLane): number[]`.
+
+## Implementation Notes
+
+Each segment runs through `distanceNm` which itself routes through
+`@suaveplan/geo`'s `greatCircleDistance` against the
+`EARTH_SPHERE` constant. The cumulative function recomputes segment
+distances rather than reusing the running sum from
+`estimateLaneDistance` — this keeps the two functions independent so
+callers can use either in isolation without paying for both. The
+trivial perf cost is acceptable at curated-dataset scale.