suaveplan/openspec/archive/2026-05-25-enterprise-ports/tasks.md

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

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

1. Scaffold

• 1.1 Create packages/geospatial/logistics/ports/ with src/ tree per design.md.
• 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.
• 1.3 tsconfig.lib.json extending ../../../../tsconfig.base.json.
• 1.4 vite.config.ts with multi-entry library build.
• 1.5 vitest.config.ts via createTestConfig with 100% coverage thresholds.
• 1.6 Scripts: build, lint, test, test:coverage, typecheck.

2. Types + errors + schemas + OTel + constants

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

3. Data

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

4. Modules

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

5. Verify

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

6. Archive

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