feat: Implement Cost Verification & Audit Engine (TASK-004) v1.3.2

ARCHITECTURE.md

@@ -255,8 +255,29 @@ Showing 20 of 4560 total requests (most recent first)
 
 These are documented but not in scope for v1. The two-function design is the right scope.
 
+## Cost Verification & Audit Engine (TASK-004)
+
+**Introduced in v1.3.0**
+
+To defend against model-level cost over-reporting or regression bugs (e.g., LiteLLM Issue #19681 / #11156), the tool includes an internal **Hardcore FinOps Audit Engine**.
+
+### How it works:
+1. **Pricing Registry**: A static mapping of model identifiers to actual provider rates (including uncached input, cached input, and output rates).
+2. **Audit Helper**: The `_audit_cost` method calculates the "True Cost" dynamically:
+   ```python
+   uncached_tokens = max(0, prompt_tokens - cached_tokens)
+   calculated_cost = (cached_tokens * input_cached_rate) + (uncached_tokens * input_uncached_rate) + (completion_tokens * output_rate)
+   ```
+3. **Discrepancy Flagging**: If the delta between LiteLLM's reported cost and our calculated cost is greater than half a cent ($0.005), it flags it with a warning `⚠️`. Otherwise, it marks it as validated `✓`.
+
+This ensures that we have immediate, live verification of context caching discounts (like Google's 90% implicit caching discount) on a per-request basis.
+
 ## Changelog
 
+### v1.3.0 (2026-06-26)
+- **feat:** Hardcore FinOps Audit Engine (TASK-004) — added `_audit_cost` helper and static `MODEL_PRICING` registry to verify reported spend against actual provider caching rates.
+- **feat:** Real-time request cost auditing in `litellm_history` output.
+
 ### v1.2.0 (2026-06-13)
 - **feat:** Natural language date shortcuts for `litellm_cost()` — `today`, `yesterday`, `monday`, `last week`, etc.
 - **feat:** Two-level zero-spend filtering — valve default (`default_hide_zero_spend`, default True) + per-call override (`hide_zero_spend`)