| 1 | # Usage Catalog |
| 2 | |
| 3 | Reasonix stores disposable usage rollups at `<cache root>/usage-catalog/v1.sqlite`. |
| 4 | Daily statistics JSONL remains authoritative and byte-compatible with older |
| 5 | versions. The catalog records file offsets and line hashes for cross-process |
| 6 | idempotency, then derives daily source/model/provider rollups. |
| 7 | |
| 8 | Only a successful JSONL append emits a non-blocking receipt. Duplicate receipts |
| 9 | cannot double-count a line. A changed hash, truncated file, replacement, queue |
| 10 | overflow, or external append triggers byte-offset reconciliation or a safe |
| 11 | per-day rebuild. Torn tails, blank lines, corrupt JSON, legacy request defaults, |
| 12 | time zones, date boundaries, and active-day semantics match the existing JSONL |
| 13 | decoder. |
| 14 | |
| 15 | SQL aggregation is used only when every selected day is complete. Otherwise the |
| 16 | existing exact JSONL query runs on explicit statistics-page access while the |
| 17 | background index catches up. Catalog failures never block provider events, |
| 18 | turn completion, controller startup, or shutdown. |
| 19 | |
| 20 | ```sh |
| 21 | reasonix doctor catalogs [--json] |
| 22 | reasonix catalogs reindex usage [--json] |
| 23 | ``` |
| 24 | |
| 25 | Diagnostics expose schema, integrity, lag, counts, and failures without model |
| 26 | request content. Reindexing never changes daily JSONL. |
| 27 |