[Public truth] Reconcile plan allowance and as_of scope

[karlwaldman]

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

[karlwaldman]

Implemented in draft PR #3 at 90d6e61f333c8aa2131e69e68356f57b0aa917f4.

Proof:

• Updated all known public free allowance claims from 200 to canonical 50 requests/month.
• Recipe 02 now names only /v1/prices/past_day, /past_week, /past_month, and /past_year, sends interval=raw, and states correction rollback coverage from 2026-07-28.
• Recipe 08 now reconciles its literal six-code watchlist: 4,320 separate hourly calls versus 720 batched calls in a 30-day month.
• Added a standard-library checker that defaults to live product-facts.json, validates every cookbook allowance claim, exact recipe-02 routes/parameters/coverage, broad and well-data as_of overclaims, and recipe-08 math. Existing weekly CI now runs its unit tests and the live check before recipe 01.
• Kept the canonical source metadata explicit: the live check reports contractVersion=2026-07-18 and reviewedAt=2026-07-18; no version bump was inferred.

Verification:

• 6 deterministic tests passed, including changed-allowance, newly introduced stale-copy, broad as_of, well-data, and math negative cases.
• The 51-request fixture exited nonzero and identified all three 50-request local claims.
• Live canonical check passed at 50 requests/month.
• Recipe 01 live production smoke passed and returned five current prices.
• Compileall and git diff --check passed.

No write-path recipe, API behavior, deployment, pricing decision, or customer action was included.

[karlwaldman]

Follow-up 4767d2a closes the pre-merge enforcement gap by running the existing smoke workflow on pull requests as well as scheduled/main runs. GitHub Actions is green: https://github.com/OilpriceAPI/cookbook/actions/runs/31438141787/job/93616857130

[karlwaldman]

Allowance-guard hardening is now pushed to draft PR #3 in commit 193da2a.

The checker now fails on stale Free claims written as requests per month, API calls/month, hyphenated/monthly variants, or an isolated numeric Free-plan table cell. Paid-plan quota rows and prose remain accepted. Proof: 9 unit tests passed (including 5 wording subtests), the live contract check reports freeRequestsPerMonth=50, and the keyless production recipe succeeded.

Detailed verification: #3 (comment)