fix(token-spy): bound usage database queries

[tang-vu]

Why this matters

The authenticated Token Spy usage endpoints passed arbitrary hours and limit values directly to the database layer. A zero/negative SQLite LIMIT can remove the row cap, while very large windows or limits create avoidable database work and unpredictable API behavior. The dashboard's supported all-time window is one year, so the public contract is now 1-8760 hours and 1-1000 usage rows.

Root cause: the FastAPI query parameters were typed but had no range constraints.

Behavioral invariant: invalid query ranges are rejected at the HTTP boundary before any database query; documented boundary values still reach the database unchanged.

Overlap check

Searched open and closed upstream PRs for Token Spy usage/query/hour/limit terms and checked PRs changing ods/extensions/services/token-spy/main.py and its tests. Existing work covers atomic writes, exception handling, pricing, logging, streaming error bodies, and SSE cursors; none bounds the /api/usage, /token-usage, or /api/summary database queries. This scope is independent.

What changed

• Bound hours to 1-8760 on usage and summary endpoints.
• Bound usage limit to 1-1000 on both the canonical endpoint and its compatibility alias.
• Added authenticated public-boundary regressions that assert rejected requests never call the database and valid maximum values are passed through.

Validation

• Red before fix: 10 failures; every invalid public query returned HTTP 200 and reached the query function.
• pytest tests/test_api_query_bounds.py -q — 11 passed.
• pytest tests -q — 31 passed, 1 skipped.
• python -m py_compile main.py tests/test_api_query_bounds.py — passed.
• git diff --check — passed.

Tradeoffs and rollback

The one-year window matches the dashboard's existing all-time selector, while 1000 rows is twice its current 500-row request and leaves headroom for API clients. Clients requesting larger exports must paginate or narrow the window. Rollback is a single commit; no persisted state or schema changes are involved.

Batch compatibility

Validated as an independent ten-PR batch from upstream main 6ff9b4fc5190099705043acaab7e9b6ad9c8b8f1. The final PR heads merged without conflicts in this order: #2964 -> #2965 -> #2967 -> #2969 -> #2970 -> #2971 -> #2972 -> #2973 -> #2974 -> #2975. The resulting local synthetic merge head is 4ae60eadad9696a9accb735aad71af87d2be802d.

Combined validation on that exact tree:

• Dashboard API boundary suites: 323 passed, 4 skipped.
• Token Spy suite: 36 passed, 1 skipped.
• Privacy Shield suite: 55 passed.
• APE suite: 47 passed.
• Python compile checks and git diff --check: passed.

The scopes are behaviorally independent. The stated order is the tested rollback/merge sequence for shared-file changes; each PR remains individually useful and revertible.