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

[karlwaldman]

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.

[karlwaldman]

Coverage-audit revision — current sprint admission

Plan v2: oilpriceapi-api#8015 supersedes earlier scheduling comments. Rank 25/70; Sunday, 2026-09-06, America/New_York. Low/medium-risk only; reclassify to a Friday/Saturday slot if boundary/compatibility risk is higher.

Intended outcome: Reconcile existing Energy Intelligence resource envelopes with Rails responses.

Gate: Use exact backend fixtures; sync/async parity, no new endpoints.

Coverage ledger: #8056. Inventory/pattern screening is complete; exhaustive semantic/runtime sign-off is not. Before implementation, review the complete affected file set and callers, revalidate against current main, supply the missing negative-path proof, and retain prior scope corrections. Prefer deletion, then simplification; correct behavior needs no PR.

No implementation is approved yet. After Karl approves: focused reversible PR → independent adversarial review → passing affected checks → merge in plan order → separately approved release/publish and artifact/customer-path verification. Maximum ten planned slots per night, not ten forced merges. If the dated window elapses before approval, re-anchor the calendar rather than backdate execution.