[Capability ledger selection 1/3] Date-range price history tool (GET /v1/prices/historical, GET /v1/prices)

[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 the largest unexposed workflow by a wide margin, both in accounts and in repeat use across two or more days. Today opa_get_history only reaches the fixed windows past_day|week|month|year, so an agent cannot ask for "Brent from 2025-01-01 to 2025-06-30" or page through a long series.

Scope (ledger rows)

• GET /v1/prices/historical
• GET /v1/prices

Either extend opa_get_history with start_date/end_date/interval and pagination, or add a sibling tool. Decide in the PR, with bounded page size and an explicit truncation notice rather than a silent partial answer (#113).

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.