docs(ble): document why GEAR/TONNEAU wire strings can't derive from tesla-protocol

[Bre77]

Intent

Captain's ask 2026-09-02: instead of hardcoding proto-enum-name strings like ShiftStateUnknown, derive them from the tesla-protocol dependency (>=1.4.0) where possible. Scope: inventory hardcoded Tesla proto-enum-name string literals across the library (grep for ShiftState and sibling enum-name literals in util.py, tesla/vehicle/vehicle.py, tesla/bluetooth.py, and elsewhere), replace each with a derivation from tesla_protocol's enum descriptors only where the derived name is BYTE-IDENTICAL to what the code compares/emits today, and leave (with an explanatory comment) any table whose derivation would require a per-value special case. Add tests pinning derived/hardcoded tables to the exact current expected strings so a tesla-protocol upgrade that renames a value fails loudly instead of silently changing behavior.

Findings: the only hardcoded proto-enum-name-string tables in the codebase are GEAR_STATES and TONNEAU_POSITION_STATES in tesla_fleet_api/tesla/vehicle/stream_glue.py, which translate VCSEC's Gear_E/ClosureState_E enum values into teslemetry-stream's ShiftState*/TonneauPositionState* wire vocabulary. Both fail the fidelity rule: Gear_E's descriptor names (GEAR_UNKNOWN/GEAR_PARK/GEAR_DRIVE/GEAR_REVERSE/GEAR_NEUTRAL) have no total stripping rule to the wire strings (PARK/DRIVE/REVERSE/NEUTRAL collapse to unrelated single letters P/D/R/N while UNKNOWN spells out in full as Unknown); ClosureState_E's CLOSURESTATE_OPEN/CLOSURESTATE_AJAR rename outright to FullyOpen/PartiallyOpen on the wire. So no code changes replace these tables - they remain hardcoded, now with comments in stream_glue.py explicitly stating why per-value special-casing is unavoidable. Separately, this inventory also surfaced that two existing tests in tests/test_ble_stream_glue.py (test_charge_port_closure_states_ingest_booleans and test_mapped_tonneau_closures_ingest_tonneau_position_strings) asserted the 'raw' metadata field by recomputing ClosureState_E.Name(state) at assertion time instead of pinning a literal expected string - a tautological check that would pass silently through a tesla-protocol rename. Fixed both to assert against literal names (e.g. "CLOSURESTATE_OPEN"), matching the pinning style already used by the sibling lock-state and gear tests in that same file. Every other proto/enum-name-shaped string literal found elsewhere (exceptions.py fault classes, const.py REST/JSON wire enums, commands.py oneof-field-name kwargs for seat heater/cooler actions) is a different kind of literal - REST wire vocabulary, Python class names, or protobuf message field names rather than enum value names copied from tesla_protocol - and is out of scope for this ask.

What Changed

• Added explanatory comments to GEAR_STATES and TONNEAU_POSITION_STATES in tesla_fleet_api/tesla/vehicle/stream_glue.py documenting why these hardcoded proto-enum-name-to-wire-string tables can't be derived from tesla-protocol's Gear_E/ClosureState_E descriptor names (no total stripping rule exists — e.g. GEAR_PARK/GEAR_DRIVE collapse to single letters, CLOSURESTATE_OPEN/CLOSURESTATE_AJAR rename outright to FullyOpen/PartiallyOpen).
• Fixed two tests in tests/test_ble_stream_glue.py (test_charge_port_closure_states_ingest_booleans, tonneau closure state test) that asserted the raw metadata field by recomputing ClosureState_E.Name(state) at assertion time — a tautological check — to instead assert against literal pinned strings (e.g. "CLOSURESTATE_OPEN"), matching the pinning style already used by sibling lock-state and gear tests, so a future tesla-protocol rename fails loudly instead of silently passing.

Risk Assessment

✅ Low: Comment-only additions plus a test-quality fix that replaces tautological Name()-recomputation assertions with pinned literal strings; no production logic changed, all tests pass, and the enum-name claims in the comments were verified against the installed tesla-protocol package.

Testing

Targeted pytest run on tests/test_ble_stream_glue.py passes (18/18), including the two tests changed to assert pinned literal enum-name strings instead of a tautological live recomputation; cross-checked those literals against the actual tesla_protocol ClosureState_E descriptor and confirmed a codebase-wide grep shows no other hardcoded proto-enum-name tables outside stream_glue.py, consistent with the stated scope and findings. No product-level runtime artifact (screenshot/CLI transcript) applies since this is a comment/test-hardening change with no new externally observable behavior.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• uv run pytest tests/test_ble_stream_glue.py -v (18 passed)
• grep for ShiftState/TonneauPositionState/CLOSURESTATE_/GEAR_ literals in util.py, tesla/vehicle/vehicle.py, tesla/bluetooth.py — none found, confirming stream_glue.py is the sole location
• uv run python3 -c ... ClosureState_E.Name() for OPEN/CLOSED/AJAR/OPENING/CLOSING — confirmed pinned literals in the updated tests byte-match the live tesla_protocol descriptor names

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.