Improve pricing schema for cache tiers, historical rates, and fast-mode verification

[TheKrush]

Summary

PromptFuel's pricing schema needs a focused cleanup pass before more quota/overage features build on it.

The audit identified three related gaps: 1-hour cache-write pricing is parsed but not used in cost math, pricing rows are not date-aware even though effective_date exists, and older Claude fast-mode rows may be stale relative to current base pricing.

Current behavior

PromptFuel has pricing data for model input/output/cache costs, and the CSV includes an effective_date field.

However:

• The 1-hour cache-write price is parsed but cost calculations still use the 5-minute cache-write price path.
• Historical usage can be re-priced using today's overwritten row because date-aware pricing lookup is not implemented.
• Older fast-mode rows for some Claude Opus variants appear inconsistent with the newer fast-mode ratio.
• Fast/base pricing relationships are not guarded by tests.
• The schema does not yet reserve a clean path for overage or plan-specific pricing.

Desired behavior

PromptFuel should use the most specific pricing fields available for the usage counters it already tracks, preserve historical pricing correctness where practical, and make fast-mode pricing drift easier to catch.

This should prepare pricing for future quota/overage work without trying to implement the whole UsagePool model in the same issue.

Requirements

• Use 1-hour cache-write pricing when 1-hour ephemeral cache creation counters are available.
• Continue using 5-minute cache-write pricing for 5-minute cache creation counters.
• Preserve existing pricing behavior where usage does not distinguish cache tier.
• Add or design date-aware pricing lookup using effective_date.
• Allow multiple pricing rows for the same model over different effective date ranges.
• Re-verify older Claude fast-mode rows against current source material before changing data.
• Add tests that catch inconsistent fast/base pricing relationships when the expected ratio is known.
• Ensure unknown models still fall back safely as they do today.

Non-goals / constraints

• Do not implement UsagePool in this issue.
• Do not implement full subscription billing or paid-overage estimation in this issue.
• Do not change historical pricing data without re-verifying the source.
• Do not remove fallback pricing behavior for unknown models.
• Do not modify CHANGELOG unless this is part of an explicit release-prep task.
• Do not assume current provider pricing is permanent.

Suggested implementation

• Split cache-write cost calculation by 5-minute and 1-hour cache counters where available.

• Add a date-aware pricing lookup API, for example:

  • lookupModelPricing(modelId, provider, usageDate?)
  • If usageDate is absent, use latest effective row.
  • If usageDate is present, choose the row effective at that date.

• Add effective_until or derive row ranges by sorting rows for the same provider/model by effective_date.

• Add tests for:

  • 5-minute cache write pricing.
  • 1-hour cache write pricing.
  • mixed cache-tier usage.
  • latest-row lookup.
  • date-aware historical lookup.
  • fast/base ratio expectations for rows where the ratio has been verified.

• Re-check older fast-mode rows before changing the CSV.

Acceptance criteria

• Cost estimates use the 1-hour cache-write rate for 1-hour cache creation counters.
• Cost estimates continue using the 5-minute cache-write rate for 5-minute cache creation counters.
• Pricing lookup can select different rows for the same model based on usage date.
• Historical usage can be priced using the row effective at that time.
• Fast-mode pricing rows have tests for verified expected ratios.
• Older fast-mode rows are either corrected with source verification or explicitly documented as unresolved.
• Unknown model fallback pricing still works.
• Existing pricing tests pass.