fix(backend): a __name__ filter needs a Key, so both usage readers ra…

[abunet]

…ised on every call

get_usage_summary and get_plan_usage_report bound their scan with where("__name__", ">=", cutoff_id), where cutoff_id is a date string like 2026-01-01. Firestore requires a Key there:

google.api_core.exceptions.InvalidArgument: 400 __key__ filter value must be a Key

Measured against the Firestore emulator: both functions raise, for every user, every time. The __name__ field is fine — the value's TYPE is not.

The document ids ARE the dates, so the cutoff is simply usage_collection.document(cutoff_id). The window is unchanged; only the type is.

Worth knowing for whoever reviews this: fixing it alone makes get_usage_summary return {} rather than raise, because a second, independent defect keeps the counters from ever nesting (a sibling PR: these documents are written with set(merge=True) and dotted keys, which Firestore stores as literal field names). With both applied, the same call against the emulator returns {'chat': {'input_tokens': 5, 'output_tokens': 3, 'call_count': 1}}. Either PR stands alone; neither restores the feature by itself.

One observation not addressed here, to keep this change to one thing: once the counters do nest, _aggregate_summary also reports plan_usage as if it were a feature ({'input_tokens': 0, ...}), because it walks every top-level map. That is a separate line and a separate decision.

Verification
emulator, before: InvalidArgument 400 key filter value must be a Key
emulator, after: the query runs and streams the in-window documents
new tests/unit/test_llm_usage_name_filter_takes_a_key.py 3 passed; passing the bare string again
fails all 3
tests/unit/test_llm_usage_db.py 19 - test_llm_usage_tracker.py 18 - test_llm_usage_endpoints.py 2

What changed and why

Product invariants affected

How it was verified

Tests

Failure class (fixes)

Failure-Class: none

Failure-class transition narrative (only when needed)

New guards (only when adding a check or ratchet)

Scoped cleanups (optional)

[kodjima33]

Confidence 4/5 (clear root cause, scoped diff ~126 lines/2 files, new dedicated regression test proving the key TypeError via emulator) — but the required 'PR Metadata Preflight'/'Hygiene' check (failure-class-protocol) fails: the PR body declares both 'Failure-Class: new' and the unfilled template's 'Failure-Class: none'. Approving but NOT merging per the CI hard floor; author needs to clean up the PR body before this can land. Note: per this PR's own body, applying it alone still leaves get_usage_summary returning {} until the sibling PR #12065 (nested-write fix) also lands.

[kodjima33]

fix(backend): name filter requires a Key not a string — confirmed still broken on main (raises 400 on every call). Root cause proven against emulator, scoped diff (126 lines), new regression tests. Not merging yet: 'Backend Hermetic Merge Gate' shows failure (downstream of a cancelled 'Detect Hermetic Backend Scope' run, likely a concurrency artifact from re-running CI on this branch) and 'Backend unit suite'/'Hygiene' are still mid-run. Confidence would be 5/5 once CI is unambiguously green — re-check before merging.

[kodjima33]

Backend bug fix, 5/5 confidence: stated root cause with reproduced Firestore error, fix(backend) title, scoped diff (124 add/2 del, 2 files), CI green (Backend unit suite + Hermetic Merge Gate pass), regression tests added (3 new, verified fail on revert). Confirmed still broken on origin/main (bare-string name filter in both get_usage_summary and get_plan_usage_report), not superseded by sibling PR #12065's separate nesting fix.