[Public truth] Reconcile plan allowance and as_of scope #2

Bottom line up front: the public Cookbook runs, but its plan and point-in-time copy have drifted beyond the canonical contracts. Correct the claims and make the weekly smoke fail on the next drift.

Verified 2026-08-10

• https://api.oilpriceapi.com/product-facts.json reports offer.freeRequestsPerMonth = 50.
• README.md, recipes/01_first_price_no_key.py, and recipes/10_resilient_client.py still say 200 requests/month.
• recipes/02_backtest_without_lookahead.py says as_of works on any history endpoint; README.md says it reconstructs any date.
• The deployed contract is narrower: past_day, past_week, past_month, and past_year, each with interval=raw; revision correction coverage currently begins 2026-07-28.
• Recipe 08 describes eight hourly requests / 5,760 monthly calls while the demonstrated watchlist has six codes; its example should reconcile to 4,320 calls in a 30-day month.
• The only CI runtime smoke executes recipe 01. It cannot detect plan-copy or scope drift.

Scope

• Correct all stale free-allowance references from the canonical product-facts contract.
• Replace the broad as_of wording with the exact four-route/raw-interval scope and coverage limits.
• Reconcile recipe 08's request-count example to the actual six-code watchlist.
• Add a standard-library public-claim check that reads the canonical product-facts endpoint and fails when local allowance copy disagrees.
• Add static assertions that prevent any history endpoint, any date, and unqualified well-data vintage claims from returning.
• Run the claim check in the existing smoke workflow.

Acceptance criteria

• README and recipes agree with live product-facts.json on the free allowance.
• Recipe 02 names only the four supported routes, requires interval=raw, and states the correction-coverage boundary.
• Cookbook wording never implies well permits or well production accept as_of.
• Recipe 08's actor-facing math matches its six-code example.
• The check exits nonzero on a fixture with a changed canonical allowance or forbidden broad as_of wording.
• Current repository check and recipe 01 production smoke pass.

Non-goals

• No pricing decision, API behavior change, customer email, or deployment.
• Do not implement the held write-path recipe in Recipe: Stop polling — alerts, webhooks, and watches (top-ARR recipe, needs write-path testing) #1.

Related: OilpriceAPI/oilpriceapi-api#6405 · OilpriceAPI/website-clean#1305