feat(usage): add AI budget usage caps

docs/06-store-data-model.md

@@ -45,6 +45,7 @@ The `Stores` struct is the top-level container holding all PostgreSQL-backed sto
 | ContactStore | `PGContactStore` | Channel contacts (auto-collected), cross-channel deduplication, merge |
 | ActivityStore | `PGActivityStore` | Audit logs, action tracking, compliance |
 | SnapshotStore | `PGSnapshotStore` | Hourly usage snapshots, cost aggregation, time series queries |
+| UsageCapStore | `PGUsageCapStore` | OpenRouter pricing catalog, pricing overrides, cap policies, reservations, counters, events |
 | SecureCLIStore | `PGSecureCLIStore` | CLI binary configs with encrypted credential injection |
 | APIKeyStore | `PGAPIKeyStore` | Gateway API keys, scopes, expiration, revocation |
 | HookStore | `PGHookStore` | Lifecycle hook definitions (event, handler type, matcher, config), execution audit log |
@@ -85,6 +86,31 @@ Migration versions:
 
 ---
 
+## Usage Cap Storage
+
+Usage cap enforcement is Standard/PostgreSQL-only in round one. The `UsageCapStore` is wired on the PostgreSQL store factory and left nil in SQLite/Lite builds.
+
+Tables:
+- `usage_pricing_catalog`: OpenRouter model catalog prices, raw upstream model payload, sync time.
+- `usage_pricing_overrides`: tenant/provider/model override prices for custom billing assumptions.
+- `usage_cap_policies`: cap definitions scoped by tenant, agent, provider, provider type, model, and window.
+- `usage_cap_counters`: current window used and reserved token/cost counters.
+- `usage_cap_reservations`: preflight reservations keyed by LLM call attempt.
+- `usage_cap_events`: allow/block/reconcile/skip audit events.
+
+Reservation updates are atomic: counters are updated only when `used + reserved + estimate` remains below configured token and cost ceilings.
+Reservation keys are idempotent per policy, so a retry using the same key does not double-increment reserved counters.
+Policy `agent_id` references must belong to the same tenant as the policy. Policy and pricing override `provider_id` references may belong to the same tenant or the master tenant for default provider fallback, but not another non-master tenant.
+Catalog and override price fields are nullable decimal strings with non-negative validation in the store layer and database checks.
+Pricing resolution checks exact override/catalog model IDs first, then provider-derived OpenRouter aliases for native unprefixed model IDs.
+
+Migration versions:
+
+- PostgreSQL: `000069_usage_caps_pricing`, `000070_usage_cap_policies`.
+- SQLite: no schema change; feature is not active in Lite.
+
+---
+
 ## 3. Session Caching
 
 The session store uses an in-memory write-behind cache to minimize database I/O during the agent tool loop. All reads and writes happen in memory; data is flushed to the persistent backend only when `Save()` is called at the end of a run.