# OpenSpec Change: enterprise-ports

- **Change ID**: enterprise-ports
- **Package**: `@suaveplan/ports`
- **Category / plugin**: `geospatial` / `logistics`
- **Target path**: `packages/geospatial/logistics/ports/`
- **Status**: PROPOSED
- **Date**: 2026-05-25
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/ports.md`
- **Main-branch source**: `/mnt/s/web/suaveplan/packages/universal/ports`

---

## Why

`@suaveplan/ports` is the canonical universal-tier global port database
on the main branch. It pairs a curated dataset of sea ports, airports,
and rail terminals (UN/LOCODE addressed) with shipping-lane waypoint
graphs and ETA estimation. The genesis branch starts empty; landing this
package unblocks every logistics/shipping consumer (`port-tracking`,
`logistics`, `customs`, `procurement`, `warehouse-ops`, and the matching
`api-plugin-*` packages) which all transitively depend on port lookups
and lane-based routing.

The reference implementation on main shipped at 95%+ coverage but
without the cross-cutting concerns mandated by the enterprise checklist
in `enterprise/ports.md`: stable typed error codes via
`@suaveplan/error`, Zod schemas at the public boundary, OpenTelemetry
instrumentation, injectable `Clock`, and 100% test coverage. This change
rebuilds the package from scratch on genesis with those additions while
preserving the full main-branch public surface so direct consumers do
not need migration shims.

## What changes

### Preserved (from main-branch surface)

- Curated port dataset split by region: `seaPortsAsia`, `seaPortsEurope`,
  `seaPortsAmericas`, `seaPortsAfricaMena`, `seaPortsOceania`, aggregated
  into `seaPorts`; plus `airports` and `railTerminals`. `allPorts`
  combines every category.
- Curated `shippingLanes` waypoint graph spanning the major global routes
  (Asia–Europe via Suez, Asia–Europe via Cape, Transpacific, Transatlantic,
  rail and air lanes).
- Port lookups: `findPort(locode)`, `findPortsByCountry(country, ports?)`,
  `findPortsByType(type, ports?)`, `searchPorts(query, ports?)`.
- Spatial lookups: `findNearestPort(coord, ports?)`,
  `findPortsInRadius(coord, radiusKm, ports?)`.
- Lane lookups: `getShippingLane(id)`, `getShippingLanesByMode(mode, lanes?)`,
  `getAllShippingLanes()`.
- Lane distance: `estimateLaneDistance(lane)`, `cumulativeDistances(lane)`
  (nautical miles, great-circle).
- Lane progress: `findPositionOnLane(coord, lane)` →
  `{ progress, remainingDistanceNm, distanceTravelledNm, nearestWaypointIndex }`.
- ETA: `estimateETA(currentCoord, lane, avgSpeedKnots?, departureTime?)` →
  `{ remainingDistanceNm, etaHours, etaDate, confidence }`.
- Types: `Port`, `PortType`, `PortFacility`, `LaneMode`, `ShippingLane`,
  `LaneProgress`, `ETAEstimate`, `NearestPortResult`.

### Added (genesis enterprise additions)

1. **Typed error registry** — `PORTS_CODES` via `defineCodes("PORTS",
   ["NO_PORTS", "INVALID_RADIUS", "INSUFFICIENT_WAYPOINTS",
   "INVALID_SPEED", "MISSING_SPEED", "INVALID_LANE", "PORT_NOT_FOUND",
   "LANE_NOT_FOUND"])`. Each code surfaces a dedicated
   `PortsError` subclass extending `SuaveplanError`.
2. **Zod schemas** for `Port`, `ShippingLane`, `SphericalCoord`,
   `LaneProgress`, `ETAEstimate`, `NearestPortResult` exposed under
   `./schemas/schemas` for boundary validation by API consumers.
3. **Injectable `Clock`** — `estimateETA(coord, lane, speed?, opts?)`
   now accepts `{ departureTime?, clock? }` so callers (jobs,
   simulation, tests) can supply a deterministic clock. `Date.now()` is
   never read at module scope.
4. **Vessel-class speed defaults** — `VESSEL_CLASS_SPEEDS` constants for
   `ulcv`, `panamax`, `feeder`, `coastal`, `freighter-air`, `rail-freight`
   used as fallbacks when neither the lane nor caller specifies a speed.
5. **OTel instrumentation** — counters `ports.lookup_total{kind}`,
   `ports.lane_lookup_total{mode}`, `ports.eta_total{confidence}`; histograms
   `ports.find_nearest_duration_ms`, `ports.lane_distance_duration_ms`,
   `ports.eta_duration_ms`. `refreshPortsMeters()` for test isolation.
6. **Spatial index** — `PortSpatialIndex` bucketed by 5-degree lat/lng
   cells, providing O(neighbours) `findNearest`/`findInRadius` instead of
   scanning all ~120 ports. Used internally by the public functions.
7. **Property-based tests** — fast-check invariants for ETA monotonicity
   (speed↑ ⇒ ETA earlier), distance triangle inequality on great-circle
   segments, and radius-containment consistency (`findPortsInRadius`
   never returns a port whose haversine distance exceeds `radiusKm`).

### Removed

Nothing. The previous proposal's `PortDatabase` class and JSON-backed
"6000-port" dataset are not part of the main-branch surface and were
aspirational; this change ships the actual surface main shipped.

## Impact

- **Affected specs**: new `ports` capability spec.
- **Affected code**: new package at `packages/geospatial/logistics/ports/`.
- **Downstream**: unblocks `port-tracking`, `logistics`, `customs`,
  `procurement`, `warehouse-ops`, and their `api-plugin-*` companions.
- **Manifest**: `MANIFEST.md` regenerated; `STATUS.md` flips `–` → `✅`.
- **Category mapping**: adds plugin `logistics` to super-category
  `geospatial` in `scripts/folder-reorg/assignment.yml` (`logistics` was
  previously a plugin without a category assignment). The 18 closed
  super-categories are unchanged.