# Tasks: enterprise-ports

**Change ID**: enterprise-ports
**Package**: `@suaveplan/ports`
**Target path**: `packages/geospatial/logistics/ports/`
**Prerequisite packages**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`, `@suaveplan/testing`

## 0. Pre-flight

- [x] 0.1 Worktree audit (`git worktree list`, `git status`) clean.
- [x] 0.2 §0a Sync — fast-forward to `genesis` HEAD (`ffe254a1`).
- [x] 0.3 Confirm `logistics` plugin added to `geospatial` super-category in `scripts/folder-reorg/assignment.yml`.

## 1. Scaffold

- [x] 1.1 Create `packages/geospatial/logistics/ports/` with `src/` tree per `design.md`.
- [x] 1.2 Write `package.json` at `0.1.0` with `"type":"module"`, `"sideEffects":false`, subpath exports, deps `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`, `@opentelemetry/api`, `zod`, `tslib`.
- [x] 1.3 `tsconfig.lib.json` extending `../../../../tsconfig.base.json`.
- [x] 1.4 `vite.config.ts` with multi-entry library build.
- [x] 1.5 `vitest.config.ts` via `createTestConfig` with 100% coverage thresholds.
- [x] 1.6 Scripts: `build`, `lint`, `test`, `test:coverage`, `typecheck`.

## 2. Types + errors + schemas + OTel + constants

- [x] 2.1 `src/types/port.types.ts` — `Port`, `PortType`, `PortFacility`, `LaneMode`, `ShippingLane`, `LaneProgress`, `ETAEstimate`, `NearestPortResult`, `SphericalCoord` (re-exported from geo).
- [x] 2.2 `src/error-codes/error-codes.ts` — `PORTS_CODES` (8 codes) + 8 `PortsError` subclasses.
- [x] 2.3 `src/schemas/schemas.ts` — Zod schemas for every public type.
- [x] 2.4 `src/otel/otel.ts` — 3 counters + 3 histograms + `refreshPortsMeters`.
- [x] 2.5 `src/constants/index.ts` — `EARTH_RADIUS_NM`, `DEFAULT_SPEED_KNOTS`, `VESSEL_CLASS_SPEEDS`, `EARTH_SPHERE` ellipsoid.

## 3. Data

- [x] 3.1 Per-region sea-port files (`sea-ports-asia`, `-europe`, `-americas`, `-africa-mena`, `-oceania`).
- [x] 3.2 `sea-ports/sea-ports.ts` aggregating all regions.
- [x] 3.3 `airports/airports.ts`, `rail-terminals/rail-terminals.ts`.
- [x] 3.4 `all-ports/all-ports.ts` combining sea + air + rail.
- [x] 3.5 `shipping-lanes/shipping-lanes.ts` with curated lanes.

## 4. Modules

- [x] 4.1 `distance` — `distanceNm`, `distanceKm` wrapping geo great-circle.
- [x] 4.2 `find-port` — `findPort`, `findPortStrict`, `findPortsByCountry`, `findPortsByType`, `searchPorts`.
- [x] 4.3 `spatial-index` — `PortSpatialIndex` with 5° bucketing.
- [x] 4.4 `nearest-port` — `findNearestPort`, `findPortsInRadius` using spatial index.
- [x] 4.5 `lane-lookup` — `getShippingLane`, `getShippingLaneStrict`, `getShippingLanesByMode`, `getAllShippingLanes`.
- [x] 4.6 `lane-distance` — `estimateLaneDistance`, `cumulativeDistances`.
- [x] 4.7 `lane-progress` — `findPositionOnLane`.
- [x] 4.8 `eta` — `estimateETA` with `{departureTime?, clock?}` opts.

## 5. Verify

- [x] 5.1 100% coverage on every module (Istanbul, branches/functions/lines/statements).
- [x] 5.2 `bunx turbo lint typecheck test build --filter=@suaveplan/ports` green.
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/ports` green at 100/100/100/100.
- [x] 5.4 Co-located `.md` (≥200 words, 6 sections) for every non-barrel `.ts`.
- [x] 5.5 Root `README.md`.
- [x] 5.6 Refresh `MANIFEST.md`; flip `STATUS.md`.

## 6. Archive

- [x] 6.1 Fold deltas into `openspec/specs/ports/spec.md` (drop `**Verified by:**` lines).
- [x] 6.2 Move folder to `openspec/archive/2026-05-25-enterprise-ports/`.