Spec: Deepen EVSE control command module

[arest]

Problem Statement

As a Home Assistant user managing one EVSE, I can start/stop charging, set charging current, and choose operation mode from multiple entry points (switch, number, select, and domain services), but the control behavior is not owned by one deep module. The same command behavior is spread across shallow modules, so fixes to error handling, refresh behavior, and idempotency require repeated changes. That increases the chance that one EVSE control path diverges from another and makes regressions harder to catch.

Solution

Introduce a deep EVSE control command module with one interface that all control adapters use. The switch, number, select, and Home Assistant service handlers become thin adapters that forward intent to this command module. The command module owns command execution, idempotency policy, refresh orchestration, and error translation. This concentrates control behavior, increases leverage for future EVSE commands, and improves locality for maintenance and testing.

User Stories

1. As a Home Assistant user, I want EVSE start charging to behave the same from a switch and a service call, so that automations and dashboard actions stay consistent.
2. As a Home Assistant user, I want EVSE stop charging to return consistent errors from every control entry point, so that troubleshooting is predictable.
3. As a Home Assistant user, I want EVSE charging current updates to follow one validation and command path, so that my automations do not break on path-specific behavior.
4. As a Home Assistant user, I want operation mode changes to use one command policy, so that eco/fast changes are reliable regardless of where I trigger them.
5. As a Home Assistant user, I want idempotent EVSE commands, so that repeated automations do not cause unnecessary writes.
6. As a Home Assistant user, I want coordinator refresh behavior after EVSE commands to be uniform, so that sensor state updates are timely and consistent.
7. As a Home Assistant user, I want authentication failures to surface in a consistent way, so that re-auth actions are clear.
8. As a Home Assistant user, I want transient EVSE API failures to be surfaced with coherent messaging, so that I can retry with confidence.
9. As a Home Assistant user, I want persistent notifications to be coherent across EVSE control actions, so that I can quickly understand what failed.
10. As a Home Assistant user, I want unsupported EVSE operation modes to fail gracefully, so that I do not accidentally assume unsupported behavior worked.
11. As an automation builder, I want one EVSE control seam behind all adapters, so that new automations do not depend on platform-specific quirks.
12. As an automation builder, I want command outcomes to be predictable, so that action retries can be designed safely.
13. As a maintainer, I want one deep EVSE command module, so that command policy changes happen in one place.
14. As a maintainer, I want higher locality for control logic, so that bugs can be fixed once and fixed everywhere.
15. As a maintainer, I want higher leverage from a single interface, so that adding future EVSE commands requires less duplicated implementation.
16. As a maintainer, I want adapters to stay shallow, so that their role is only translation to and from Home Assistant platform shapes.
17. As a maintainer, I want error taxonomy ownership in one module, so that command callers do not each reinvent error handling.
18. As a maintainer, I want command telemetry and logging to be centralized, so that operational diagnosis is easier.
19. As a tester, I want tests to cross one command interface seam, so that behavior coverage is strong without copying implementation.
20. As a tester, I want to verify command behavior without loading full Home Assistant runtime details, so that tests are fast and stable.
21. As a tester, I want adapter tests focused on translation only, so that they assert interface contracts rather than duplicated command internals.
22. As a contributor, I want clear module responsibilities, so that pull requests are easier to reason about.
23. As a contributor, I want deletion-test clarity, so that shallow wrappers are not reintroduced around EVSE command behavior.
24. As a support engineer, I want consistent user-facing failure behavior across control surfaces, so that runbooks stay simple.
25. As a release manager, I want a single command seam to regression-test, so that releases have lower EVSE control risk.
26. As a Home Assistant user, I want EVSE control reliability to remain stable as new control features are added, so that upgrades feel safe.
27. As a maintainer, I want the EVSE Sensor Catalog and control behavior to remain decoupled at a clear seam, so that telemetry evolution does not destabilize command paths.
28. As a maintainer, I want future protocol changes in the Daze backend to be absorbed in one control module implementation, so that adapter churn is minimized.
29. As a tester, I want fixtures and assertions shared around the command interface, so that new command actions get coverage by default.
30. As a product owner, I want consistent EVSE command behavior across UI and automation paths, so that user trust in the integration increases.

Implementation Decisions

• Use one primary seam: an EVSE control command module interface that represents command intent (start, stop, set current, set mode).
• Keep existing Home Assistant-facing modules as adapters. Their interface to callers remains unchanged where possible; their implementation becomes forwarding logic.
• Consolidate command implementation behind the new command module: API invocation, idempotency policy, refresh orchestration, error translation, and notification strategy.
• Preserve the existing EVSE domain language and keep command semantics anchored to EVSE actions, not platform-specific behavior.
• Keep API transport details behind adapter seams; command callers should depend on command outcomes, not transport mechanics.
• Maintain a clear separation between EVSE command behavior and EVSE Sensor Catalog behavior.
• Prefer extending existing seams over introducing multiple new seams; target one dominant command seam for this feature.
• Apply the deletion test during implementation review: removing adapter-local command logic should not reintroduce scattered behavior.
• Keep unsupported command states explicit in the command interface contract so adapters can provide stable UX without owning business decisions.
• Define a stable error contract at the command seam for auth failures, transient backend failures, and unsupported operations.

Testing Decisions

• Good tests assert external behavior at module interfaces, not internal call sequences or private implementation details.
• Primary tests target the EVSE control command module interface as the highest seam, covering success paths, idempotency, refresh behavior, and error translation.
• Adapter tests stay shallow and verify translation: incoming Home Assistant actions map to the correct command intent and surfaced outcomes.
• Regression tests ensure parity: switch, number, select, and service adapters must produce equivalent command outcomes for equivalent intents.
• Error-behavior tests verify consistent user-facing outcomes for auth failures, transient failures, and unsupported mode selection.
• Prior art: existing tests already validate pure EVSE control logic and session derivations; this feature reorients that testing effort to runtime module interfaces rather than copied implementation.
• Add deletion-test-oriented checks during review to prevent reintroduction of duplicated command behavior in adapters.

Out of Scope

• Redesigning EVSE onboarding workflow and token-entry flow.
• Changing EVSE Sensor Catalog key set, sensor semantics, or diagnostics definitions.
• Adding new EVSE user-visible control capabilities beyond current start/stop/current/mode intents.
• Reworking Home Assistant UI copy, translations, or dashboard cards unrelated to control command behavior.
• Protocol-level backend changes in the Daze cloud API.

Further Notes

• No ADRs were found in the repository area for this scope, so no ADR conflict is currently recorded.
• This spec intentionally optimizes for locality and leverage in the EVSE control path because those modules are active hot spots in recent history.
• If future architecture work continues, the next likely deepening candidate is the EVSE onboarding workflow module, but that is intentionally deferred from this spec.