[Capability ledger selection 3/3] Marine workflows: ports, all-port prices, marine-fuel history

[karlwaldman]

Why this was selected

Ranked by 30-day production demand (api_requests, window ending 2026-09-13) among REST workflows the MCP server does not expose. Population: authenticated accounts with at least one successful call. Excluded: internal-service, admin, internal-domain and smoke accounts; accounts younger than the window; and catalogue sweepers (25 or more distinct method+path keys). The query and the account-level numbers are in the #77 PR description and in the private evidence Karl holds; this public issue carries only the ranking.

This is third, tied on accounts with commodity detail/coverage, which stays deferred. It was chosen on repeat use and call volume, where marine is clearly ahead; at this sample size, demand only weakly separates ranks 2 to 4, and the PR says so. opa_get_marine_fuels returns latest prices only, through the compatibility alias /v1/marine-fuels/latest.

Scope (ledger rows)

• GET /v1/marine-ports
• GET /v1/marine-ports/{port_code}
• GET /v1/prices/marine-fuels
• GET /v1/prices/marine-fuels/historical

Also move opa_get_marine_fuels from the compatibility alias to canonical GET /v1/prices/marine-fuels/latest (the API route policy lists /v1/marine-fuels/latest as a deprecated alias).

Acceptance criteria (from #77)

• Input schema: a zod input schema with bounded parameters and no free-form path segments; invalid input returns an MCP error before any network call.
• Entitlement behavior: 401, 402/403 and 429 are classified on the API's own signal. Follow fix(errors): stop blaming the plan for a bad key, a 404 or a 5xx (#103) #111/fix(limits): classify a 429 in alertHttpError on the API's signal, not the status (#109) #112: a bad key, a 404 or a 5xx is never reported as a plan limit. An entitlement refusal names the plan or add-on the API reports.
• Unit tests: mocked-fetch vitest coverage for success, empty data, the entitlement refusal, and the formatter never printing an absent field as data (fix(render): never print an absent field as data (#105) #110).
• Live-contract entry: the new tool has an explicit LIVE_CONTRACT_CATALOG entry, so npm run smoke:live-contract-matrix stays green (coordinate the catalog shape with [P2][bug] The live contract matrix asserts the envelope, never the fields a formatter reads — it cannot catch a rename #118).
• Ledger: the rows listed below flip from not_exposed / selected to exposed, naming the tool, with ledgerVersion bumped and a changes entry. npm run check:capability-ledger stays green.
• Release notes link the ledger change.

Part of #77.