feat(marine): port directory and marine-fuel history tools; canonical latest path (#125)

[karlwaldman]

Part of #125 (selection 3 of the #77 capability ledger). Ships three of the four ledger rows plus the canonical-path move; GET /v1/prices/marine-fuels stays selected and not exposed (see "Not in this PR").

What changes

Tool	REST	Notes
opa_get_marine_ports (new)	GET /v1/marine-ports, GET /v1/marine-ports/{port_code}	Directory with region / country / major_only filters, or one port by UN/LOCODE or name with prices collected in the last 24 h. A 404 names the unknown port and points at the directory, never the plan.
opa_get_marine_fuel_history (new)	GET /v1/prices/marine-fuels/historical	port_code (5-letter UN/LOCODE), fuel_type enum VLSFO/MGO_05S/HFO_380/HFO_180, days 1-365 (default 30). One row per assessment date (latest collection kept), high/low when currency and unit agree, explicit note when the earliest row is later than the requested window start.
opa_get_marine_fuels	now GET /v1/prices/marine-fuels/latest?limit=100	Was the deprecated alias /v1/marine-fuels/latest. limit=100 is the API cap; default is 50 series rows.

Ledger ledgerVersion 3 -> 4 with a changes entry: the three rows flip to exposed, the via alias is dropped from the latest row, the family lists all three tools. Release notes should link ledger v4.

Backend contract (oilpriceapi-api origin/main, read-only)

• /v1/marine-ports* (V1::MarineFuelPortsController): authenticated, no feature gate; Rack::Attack marine-fuel/api throttle 30/min per token.
• /v1/prices/marine-fuels/historical (V1::PricesController#marine_fuels_historical): 403 {"error":"Historical marine fuel data requires a paid subscription"} when plan == 'free' and no live trial; port_code + fuel_type required (400 otherwise); days clamped 1-365; limit(1000) rows; Rack::Attack marine-fuel/historical 5/min per token.
• Not gated on :marine_bunker_data. That feature gates /v1/bunker-fuels/* and /v1/maritime-fuels/*, not these routes.
• Descriptions state the plan boundary ("paid subscription or an active trial; other accounts get HTTP 403") and that history is rate-limited more tightly and row-capped. They give no numbers, because smoke:public-claims rejects hard-coded rate and plan claims. The numbers are above.

Two backend defects found while verifying:

• Bare fuel_type=VLSFO on history returns an empty 200. The tool sends the series code VLSFO_SGSIN_USD, which matches exactly today and still works after a backend fix. Re-verified on OilpriceAPI/oilpriceapi-api#7774.
• days=365 returns 1,000 rows covering only 68 dates, because the cap is spent on repeated collections. metadata.count counts ports, not rows. Filed OilpriceAPI/oilpriceapi-api#9641. The tool de-duplicates per date and says when the window was cut short.

Red / green

• Red: src/__tests__/marineWorkflows.test.ts against unchanged src/index.ts: 20 failed / 0 passed.
• Green: the same file passes 20/20. Full suite: 571/571 in one run. One other run hit the known timing flake in energyPlugin.test.ts > cancels an upstream that stalls…, which this PR does not touch ([P2][test] energyPlugin 'cancels an upstream that stalls' times out intermittently (2/5 local runs on origin/main) #172).
• New tools were also added to the [P1][bug] 14 tools still blame the plan's entitlement for a bad API key, a 404 or a 5xx — #94 fixed one of 15 #103 entitlement-misattribution sites (401/404/5xx never read as plan limits) and the Tool descriptions don't state tier requirements — agents discover the paywall by probing #63 gated-description check. Tool-count assertions went 36 -> 38 (read profile 32 -> 34).
• Fixtures in src/__tests__/fixtures/marineWorkflowsLive.ts are verbatim live payloads (366 lines). Source change is about 240 lines in src/index.ts.

Checks run locally

• npm test: green, apart from the [P2][test] energyPlugin 'cancels an upstream that stalls' times out intermittently (2/5 local runs on origin/main) #172 flake
• npm run build and tsc --noEmit: clean, 38 tools in the manifest
• npm run check:capability-ledger: OK capability ledger v4: 118 published operations … (40 exposed, 78 not exposed, 6 selected); 38 registered tools
• npm run generate:live-contracts and npm run smoke:live-contract-matrix: passed
• npm run smoke:public-claims: passed, 76 surfaces

Live verification (production, smoke key, 2026-10-15)

scripts/live-smoke.mjs with the real handlers: PASSED for opa_get_marine_ports, opa_get_marine_fuel_history and opa_get_marine_fuels (HTTP 200, formatter fields present). The runner's only failures are the write-contract tools it skips without SMOKE_WRITE_CONTRACTS=1.

Direct handler calls against production:

• opa_get_marine_ports {}: 8 ports (SGSIN, NLRTM, USHOU, AEFUJ, HKHKG, USLAX, BRSSZ, USNYC)
• opa_get_marine_ports {port:"Singapore"}: SGSIN detail and 3 prices from the last 24 h
• opa_get_marine_ports {port:"XXXXX"}: The API has no marine port "XXXXX" (HTTP 404)…
• opa_get_marine_fuel_history SGSIN VLSFO 7: 5 dates, High 917 / Low 889.5 USD metric_ton
• opa_get_marine_fuel_history SGSIN VLSFO 365: 68 dates from 1000 rows, with the earliest-assessment note (2026-07-27 vs 2025-10-15)
• opa_get_marine_fuel_history SGSIN HFO_180 30: empty, named as such and pointed at fuel services, no plan wording
• opa_get_marine_fuels {port:"NLRTM"} on the canonical path: 3 prices

Unverified: the live 403 for a free account without a trial. No free key was available. That case is covered by reading the backend code and by a unit test on the API's verbatim error body.

Not in this PR

• GET /v1/prices/marine-fuels stays selected. Live it is a paginated feed of the 100 most recent collections: 62 rows across 8 ports, several per fuel. That overlaps latest (one per series) and history (per-port series), so a separate tool adds little. It needs a decision: reclassify it as deferred/alias in the ledger, or expose it as a follow-up.
• The remote energy_marine_fuels facade (src/energyPlugin.ts) still calls the /v1/marine-fuels/latest alias. It is a separate surface and was left unchanged.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: ead0cafb-a468-4f72-ac76-7b0a16a983df

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[karlwaldman]

Reviewed canonical latest path, port directory and single-port behavior, daily history deduplication, bounded dates, entitlement and empty-data recovery. Corrected the obsolete 24-hour claim to the deployed seven-day observation window and added observed date/age/stale fields with a weekend regression test. Preserved futures-history integration and exact inventory of 40 registered / 36 read-only tools. Validation: 643 tests, build and packed protocol checks, pai-check TypeScript, and exact-provenance non-root Docker smoke; all current CI checks green.