[P1][Coverage review] Reconcile existing Energy Intelligence resource envelopes with Rails responses #107

Goal

Reconcile existing Energy Intelligence resource envelopes with Rails responses

Evidence at frozen review baseline

oilpriceapi/resources/ei/rig_counts.py:99 declares by_basin as List[Dict] but returns the entire response.data object. app/controllers/v1/ei/rig_counts_controller.rb:33 returns data:{report_date,basins:[...]}. A mock of the actual public Python method returned a dict with keys report_date and basins, not the documented list. by_state and historical use named states/records collections; async_resources.py repeats generic unwrapping. Latest/type/example field names also need comparison to the actual controller, not an invented flat fixture.

Smallest change / deletion first

Correct only already-shipped EI methods and their truthful response types/examples. Use endpoint-specific backend fixtures; remove redundant generic unwrapping/guessing rather than adding a second response abstraction. Do not use this ticket to add LTL, subscription lifecycle or other new endpoints.

Acceptance and negative-path proof

• Add a table mapping all existing sync/async EI methods to backend route, success envelope and named fields; record already-correct methods with no changes.
• Red fixtures reproduce by_basin/by_state/historical named collections through actual client transport, not a mocked resource that bypasses unwrapping.
• Choose/document the smallest compatible public contract; preserve metadata where the public contract requires it and do not silently break callers with a broad global unwrap change.
• Test valid, empty, missing-collection, malformed-row, 401/403/429 and async parity; failures are explicit, never fabricated empty success.
• Run full relevant tests and packed-install examples using the selected version.

Risk, delivery and rollback

MEDIUM — read response contract; no server/data mutation. Any breaking public-contract change needs versioning approval.

Planning only. Reproduce against current main and check intervening/duplicate work before implementation. One focused reversible PR per admitted change, independent adversarial review, ordered merge and approved release/publish with artifact proof. If no change is needed, close with evidence. Rollback must preserve customer data and restore only a known-safe version; do not restore an unsafe public entrypoint to resolve an ownership question.

Parent plan: https://github.com/OilpriceAPI/oilpriceapi-api/issues/8015 . No application changes, remote abuse probes or production writes were made during this audit.