[GraciousGazelles]

Summary

Adds a bounded read-only exact-root usage report with per-model and root/descendant token accounting, plus synthetic tests for lineage, model attribution, limits, and read-only behavior.

The report explicitly identifies which ledger was selected and does not claim cross-ledger deduplication or complete historical coverage. Hosted validation is required before any local report run.

Scope

This change adds the report command and its synthetic policy test. It does not modify the usage writer, schema, or database.

[gemini-code-assist]

Code Review

This pull request introduces a bounded exact-root usage reporting mechanism and fallback strategies for older database schemas. Key changes include adding support for model-by-model breakdowns in metrics, implementing a single-pass metadata snapshot fallback when reporting indexes are missing, and adding robust error handling and limit enforcement for lineage scans. Additionally, a comprehensive test suite has been added to verify these behaviors under various database index configurations. There are no review comments to address, and the implementation appears solid.